Todoist
Extend the Todoist platform with our powerful APIs.

Introduction to the standard API

Todoist standard API can be used to hook Todoist into other applications. If you need some functionality, don't hesitate to post it on Todoist Support Page.

If your application needs to maintain a complete model of the data and sync this model we recommend using Todoist Sync API.

Table of contents

Solving cross domain security policy [top]

You can't use AJAX to directly communicate with Todoist, this is due to browser security policy. You can solve this by communicating with Todoist using a script tag:
                var script = document.createElement('script');
                script.type = 'text/javascript';
                script.src = 'https://api.todoist.com/API/...&callback=callbackFunction';
                document.getElementsByTagName('head')[0].appendChild(script);
            
The response data will look like this (callbackFunction will be called):
                callbackFunction({ JSON data here });
            

Users [top]

User's JSON properties

A user in Todoist is a JSON object. The dates will be in UTC timezone. Typically a user object will look like:
            {
              "start_page": "_info_page",
              "api_token": "d18a76ab310947100kc60fe9b3cdc466515bb3a1",
              "time_format": 0,
              "sort_order": 0,
              "full_name": "Joh Doe",
              "mobile_number": "",
              "mobile_host": "",
              "timezone": "Europe/Copenhagen",
              "id": 1,
              "date_format": 1,
              "premium_until": "Sat Sep 22 13:15:03 2018",
              "default_reminder": "no_default",
              "email": "john@doe.com"
            }
            
Explanation of the different properties:
id: User's unique id.
api_token: User's token (that should be used to call the other API methods).
email: User's email.
full_name: User's real name.
start_page: User's default view on Todoist.
timezone: User's timezone in a string.
tz_offset: User's timezone offset [GMT_STRING, HOURS, MINUTES, IS_DAYLIGHT_SAVINGS_TIME].
time_format: If it's 0 then show time as 13:00, else show time as 1pm.
date_format: If it's 0 then show dates as DD-MM-YYYY, else show dates as MM-DD-YYYY.
sort_order: If it's 0 then show Oldest dates first when viewing projects. Else Oldest dates last.

mobile_number: User's mobile number
mobile_host: User's mobile host

premium_until: When does the user's premium subscription expire?
default_reminder: What is the default reminder for the user? Reminders are only possible for premium users. default_reminder can be following

/API/login should be HTTPS

Login user into Todoist to get a token. Required to do any communication.
Required parameters:
email: User's email
password: User's password
Successful return:
HTTP 200 OK with a JSON object with user data:
                {
                  "email": "...",
                  "token": ...,
                  ...
                }
                
Error returns:
"LOGIN_ERROR"

/API/loginWithGoogle should be HTTPS

Login user into Todoist with Google account. Can be used instead of /API/login to get a token.
Implementation notes:
While authenticating, application exchanges their users' OAuth 2.0 access tokens to tokens provided by Todoist. OAuth 2.0 access token must be issued for the scope "oauth2:https://www.googleapis.com/auth/userinfo.email"

It doesn't matter how you receive the access token. Android applications can use AccountManager to get it done. Other developers should consider using generic authentication instructions.
Required parameters:
email: User's email
oauth2_token: OAuth 2.0 access token, received by application from user.
Optional parameters:
auto_signup: If set to "1" and user with this email and Google Account doesn't exist yet, then automatically register a new account
full_name: User's full name if user is about to be registered. If not set, a user email nickname will be used.
timezone: User's timezone if user is about to be registered (check /API/getTimezones). If not set, we guess the timezone from client IP address. In case of failure "UTC" timezone will be set up for a newly created account.
lang: User's language. Can be de, fr, ja, pl, pt_BR, zh_CN, es, hi, ko, pt, ru, zh_TW
Successful return:
HTTP 200 OK with a JSON object with user data:
                {
                  "email": "...",
                  "token": ...,
                  ...
                }
                
Error returns:
"LOGIN_ERROR": Raises when the token is invalid or outdated (Google refuses to accept this token.)
"INTERNAL_ERROR": If server is unable to connect with Google to check the token or if the response from Google is unable to parse. It makes sense to repeat the attempt with same set of options later.
"EMAIL_MISMATCH": The token is valid, but the email accompanied the token in the request mismatches the one returned by Google.
"ACCOUNT_NOT_CONNECTED_WITH_GOOGLE": Raises when token is valid and matches the email, but Todoist account is not connected with Google.

/API/ping

Test user's login token.
Required parameters:
token: User's login token
Successful return:
HTTP 200 OK with text:
"ok"
Error returns:
HTTP 401 - "Token not correct!"

/API/getTimezones

Returns the timezones Todoist supports.
Successful return:
HTTP 200 OK with a JSON object with timezone names:
                ["US/Alaska", "US/Arizona", "US/Central", "US/Eastern", ...]
                

/API/register should be HTTPS

Required parameters:
email: User's email
full_name: User's full name
password: User's password, should be at least 5 characters long
Optional parameters:
lang: User's language. Can be de, fr, ja, pl, pt_BR, zh_CN, es, hi, ko, pt, ru, zh_TW
timezone: User's timezone (check API call /API/getTimezones). As default we use the user's IP address to determine the timezone.
Successful return:
HTTP 200 OK with a JSON object with user data:
                    {"email": "...", "token": ..., ...}
                    
Error returns:
"ALREADY_REGISTRED"
"TOO_SHORT_PASSWORD"
"INVALID_EMAIL"
"INVALID_TIMEZONE"
"INVALID_FULL_NAME"
"UNKNOWN_ERROR"

/API/deleteUser should be HTTPS

Required parameters:
token: User's token
current_password: User's current password
Optional parameters:
reason_for_delete: Reason for deletion (used for feedback)
in_background: Default is 1. Set it to 0 if you want the user deleted instantly (and not in a background worker).
Successful return:
HTTP 200 OK with text:
"ok"
Error returns:
HTTP 403 Forbidden if the password does not match.

/API/updateUser should be HTTPS

Required parameters:
token: The user's token (received on login)
Optional parameters:
email: User's email
full_name: User's full name
password: User's password, should be at least 5 characters long
timezone: User's timezone (check /API/getTimezones)
date_format: How should dates be formatted? If 0 DD-MM-YYYY will be used, if 1 MM-DD-YYYY will be used
time_format: How should times be formatted? If 0 '13:00' will be used, if 1 '1:00pm' will be used
start_day: First day of week. 1 for Monday, 7 for Sunday
next_week: When postponing what day should we choose? 1 for Monday, 7 for Sunday
start_page: Can be following values:
  • _blank to show blank page,
  • _info_page to show info page,
  • _project_$PROJECT_ID, where $PROJECT_ID is the id of the project to show
  • $ANY_QUERY to query after anything (for example tod,tom,!!1)
default_reminder: Can be following values:
  • email to send reminders by email
  • mobile to send reminders to mobile devices via SMS
  • push to send reminders to smart devices using push notifications (one of Android or iOS official client must be installed on the client side to receive these notifications)
  • no_default to turn off sending default reminders
Successful return:
HTTP 200 OK with a JSON object with user data:
                    {"email": "...", "token": ..., ...}
                    
Error returns:
"ERROR_PASSWORD_TOO_SHORT"
"ERROR_EMAIL_FOUND"

/API/updateAvatar should be HTTPS

Required parameters:
token: The user's token (received on login)
Optional parameters:
image: Avatar image. The request must be encoded with multipart/form-data. Maximum avatar size is 2 Mb.
delete: If this flag is set to true, then current avatar will be removed, and a default one will be used instead.
Successful return:
HTTP 200 OK with a JSON object with user data:
                    {"email": "...", "token": ..., ...}
                    
If user avatar is uploaded, every user-related response will have three avatar-related fields: avatar_big, avatar_medium and avatar_small, containing URLs for user avatars in different resolution. Also there is an image_id field, containing the unique part of the avatar URL, or null if avatar is not uploaded.
Error returns:
"UNKNOWN_IMAGE_FORMAT"
"UNABLE_TO_RESIZE_IMAGE"
"IMAGE_TOO_BIG"
"UNABLE_TO_RESIZE_IMAGE"

/API/getRedirectLink should be HTTPS

Required parameters:
token: The user's token (received on login)
Optional parameters:
path: The path to redirect user's browser (default is "/app")
hash: The hash part of the path to redirect user's browser.
Successful return:
It returns a HTTP 200 OK response with a JSON-encoded object, containing the absolute URL to redirect or to open in a browser. For the first time the link logs in the user automatically and performs a redirect to a given page, but once used, the link keeps working as a plain redirect. The link keeps working as a login link for as long as one week after it's been issued.
                {"link": "https://todoist.com/secureRedirect?..."}
                

/API/getProductivityStats

Returns' the user's recent productivity stats.
Required parameters:
token: The user's token (received on login)
Successful return:
HTTP 200 OK with a JSON object with user data:
            {
              "karma_last_update": 2,
              "karma_trend": "up",
              "days_items": [
                {
                  "date": "2014-05-30",
                  "items": [
                    {
                      "completed": 1,
                      "id": 14681
                    },
                    ...
                  ],
                  "total_completed": 2
                },
                ...
              ],

              "week_items": [
                {
                  "date": "2014-05-12\/2014-05-18",
                  "items": [
                    {
                      "completed": 7,
                      "id": 14681
                    },
                    {
                      "completed": 14,
                      "id": 966471
                    },
                    ...
                  ],
                  "total_completed": 116
                },

                ...
              ],

              "project_colors": {
                "966471": 17,
                "1246213": 21,
                ...
              },

              "karma_graph": "https://..."
            }
            

Projects [top]

Project's JSON properties

A project in Todoist is a JSON object. Typically a project object will look like this:
            {
              "user_id": 1,
              "name": "Babu",
              "color": 2,
              "collapsed": 0,
              "item_order": 1,
              "cache_count": 0,
              "indent": 1,
              "id": 455831,
              "last_updated": "1325774561.4"
            }
            
Explanation of the different properties:
id: The unique id of the project.
user_id: The unique id of the user that owns the project.
name: The name of the project. If the name starts with a star * then the name is a group. In this example, * Life is a group:
cache_count: How many items does the project hold?
note: this attribute is deprecated and is not updated on any API calls. If you want to get the number of items in the project, you should fetch all the project's items.
color: The color of the project, an index is an array.

indent: The indent of the item (a number between 1 and 4 where 1 is top-level).
item_order: Project's order in the project list. Smaller number should be located in the top.
collapsed: If set to 1 the project's sub projects are collapsed. Otherwise they aren't.
last_updated: A timestamp when the project was last updated (updated means, name changed, task added, task completed etc.)

/API/getProjects

Returns all of user's projects.
Required parameters:
token: The user's token (received on login)
Successful return:
HTTP 200 OK with a JSON list of all of user's projects:
                    [{
                      "user_id": 1,
                      "name": "Test project",
                      "color": 1,
                      "collapsed": 0,
                      "item_order": 1,
                      "indent": 1,
                      "cache_count": 0,
                      "id": 22073
                    }, {
                      "user_id": 1,
                      "name": "Another test project",
                      "color": 2,
                      "collapsed": 0,
                      "item_order": 2,
                      "indent": 1,
                      "cache_count": 0,
                      "id": 22074
                    }, ...]
                    

/API/getProject

Return's data about a project.
Required parameters:
token: The user's token (received on login)
project_id: The id of the project to fetch
Successful return:
HTTP 200 OK with a JSON object with project data
                    {
                      "user_id": 1,
                      "name": "Test project",
                      "color": 1,
                      "collapsed": 0,
                      "item_order": 1,
                      "indent": 1L,
                      "cache_count": 0,
                      "id": 22073
                    }
                
Error returns:
"ERROR_PROJECT_NOT_FOUND"

/API/addProject

Add a new project.
Required parameters:
name: The name of the new project
token: The user's token (received on login)
Optional parameters:
color: The color of the new project
indent: The indent of the item (a number between 1 and 4 where 1 is top-level).
order: The order of the new project
Successful return:
HTTP 200 OK with a JSON object with project data:
                    {"name": "...", "user_id": ..., ..., "collapsed": 0L, "id": 22000}
                    
Error returns:
"ERROR_NAME_IS_EMPTY"

/API/updateProject

Update an existing project.
Required parameters:
project_id: The id of the project to update
token: The user's token (received on login)
Optional parameters:
name: New name of the project
color: New color of the project
indent: The indent of the item (a number between 1 and 4 where 1 is top-level).
order: The order of the project
collapsed: 1 if the project$ should be collapsed, 0 if it should not be collapsed
Successful return:
HTTP 200 OK with a JSON object with project data:
                    {"name": "...", "user_id": ..., ..., "collapsed": 0L, "id": 22000}
                    
Error returns:
"ERROR_PROJECT_NOT_FOUND"

/API/updateProjectOrders

Updates how the projecta are ordered.
Required parameters:
token: The user's token (received on login)
item_id_list: A JSON list of the project's order, could be [3,2,9,7]
Successful return:
HTTP 200 OK with text:
"ok"
Error returns:
"ERROR_PROJECT_NOT_FOUND"

/API/deleteProject

Delete an existing project.
Required parameters:
project_id: The id of the project to update
token: The user's token (received on login)
Successful return:
HTTP 200 OK with text:
"ok"

/API/getArchived

Return's users archived projects.
Required parameters:
token: The user's token (received on login)
Successful return:
HTTP 200 OK with JSON list of archived projects:
[{...}, ...]

/API/archiveProject

Archive project and its children. Only available for Todoist Premium users.
Required parameters:
project_id: The id of the project to archive
token: The user's token (received on login)
Successful return:
HTTP 200 OK with a JSON list of projects that have been archived:
                    [12323,24242,2424]
                    

/API/unarchiveProject

Unarchive project and its children. Only available for Todoist Premium users.
Required parameters:
project_id: The id of the project to unarchive
token: The user's token (received on login)
Successful return:
HTTP 200 OK with a JSON list of projects that have been unarchived:
                    [12323,24242,2424]
                    

Labels [top]

Labels are added automatically by inserting @tag in a task's content field.

/API/getLabels

Returns all of user's labels.
Required parameters:
project_id: The id of the project to update
token: The user's token (received on login)
Optional parameters:
as_list: If as_list is set to 1 then this method returns a list of labels, like ["home", "office"] - - instead of a object of labels.

/API/addLabel

Adds a label or returns an existing label.
Required parameters:
name: The name of the old label
token: The user's token (received on login)
Optional parameters:
color: The color of the label
Successful return:
HTTP 200 OK with JSON object:
                {"name": ..., "color": ..., ...}
                

/API/updateLabel

Changes the name of an existing label.
Required parameters:
old_name: The name of the old label
new_name: The name of the new label
token: The user's token (received on login)
Successful return:
HTTP 200 OK with updated JSON object:
                    {"name": ..., "color": ..., ...}
                    

/API/updateLabelColor

Changes the name of an existing label.
Required parameters:
name: The name of the label
color: The color of the label
token: The user's token (received on login)
Successful return:
HTTP 200 OK with updated JSON object:
                    {"name": ..., "color": ..., ...}
                    

/API/deleteLabel

Deletes an existing label.
Required parameters:
name: The name of the label to delete
token: The user's token (received on login)
Successful return:
HTTP 200 OK with text:
"ok"

Items [top]

Item's JSON properties

A item in Todoist is a JSON object. The dates will be in UTC timezone. Typically a item object will look like:
            {
              "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": ""
            }
            
Explanation of the different properties:
id: Unique task id.
user_id: The owner of the task

due_date: When is the date due next? If js_date is set to 1 this date will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise it will be formatted as "Sun Apr 29 2007 23:59:59". Inspect on the date_string to see if the time is included and should be rendered.
date_string: How did the user enter the task? Could be every day or every day @ 10. The time should be shown when formating the date if @ OR at is found anywhere in the string

collapsed: If set to 1 the task's sub tasks are collapsed. Otherwise they aren't.
indent: The indent of the item (a number between 1 and 4 where 1 is top-level).

Passing in date_string and due_date

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.

/API/getUncompletedItems

Returns a project's uncompleted items (tasks).
Required parameters:
project_id: The id of the project to update
token: The user's token (received on login)
Optional parameters:
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
Successful return:
HTTP 200 OK with a JSON object with user data:
                [{
                  "due_date": new Date("Sun Apr 29 2007 23:59:59"),
                  "user_id": 1,
                  "collapsed": 0,
                  "in_history": 0,
                  "priority": 1,
                  "item_order": 1,
                  "content": "By these things",
                  "indent": 1,
                  "project_id": 22073,
                  "id": 210870,
                  "checked": 0,
                  "date_string": "29. Apr 2007"
                }, {
                  "due_date": null,
                  "user_id": 1,
                  "collapsed": 0,
                  "in_history": 0,
                  "priority": 1,
                  "item_order": 2,
                  "content": "Milk",
                  "indent": 2,
                  "project_id": 22073,
                  "id": 210867,
                  "checked": 0,
                  "date_string": ""
                }, ...]
                
Error returns:
"ERROR_PROJECT_NOT_FOUND"

/API/getAllCompletedItems

Returns all user's completed items (tasks). Only available for Todoist Premium users.
Required parameters:
token: The user's token (received on login)
Optional parameters:
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
project_id: Filter the tasks by project_id
limit: The number of items to return (default is 30)
from_date: Return items with a complete date same or older than from_date (formated as "2007-4-29T10:13"). Notice that this can include duplicates.
Successful return:
HTTP 200 OK with a JSON object:
                {
                  "items": [{
                    "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": 210872,
                    "checked": 1,
                    "date_string": ""
                  }, {
                    "due_date": null,
                    "user_id": 1,
                    "collapsed": 0,
                    "in_history": 1,
                    "priority": 1,
                    "item_order": 1,
                    "content": "Test",
                    "indent": 1,
                    "project_id": 22073,
                    "id": 210871,
                    "checked": 1,
                    "date_string": ""
                  }...]
                }
                
Error returns:
"ERROR_PROJECT_NOT_FOUND"

/API/getItemsById

Required parameters:
ids: A JSON list of ids to fetch
token: The user's token (received on login)
Optional parameters:
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
Successful return:
HTTP 200 OK with a JSON list with item objects. Example:
https://api.todoist.com/API/getItemsById?ids=[210873,210874]&token=fb5f22601ec566e48083213f7573e908a7a272e5
                [{
                  "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": ""
                }, {
                  "due_date": null,
                  "user_id": 1,
                  "collapsed": 0,
                  "in_history": 1,
                  "priority": 1,
                  "item_order": 1,
                  "content": "Test",
                  "indent": 1,
                  "project_id": 22073,
                  "id": 210874,
                  "checked": 1,
                  "date_string": ""
                }...]
                

/API/addItem

Adds an item to a project.
Required parameters:
content: The text of the task
token: The user's token (received on login)
Optional parameters:
project_id: The id of the project to add to, defaults to Inbox project
date_string: The date of the task, added in free form text. Examples of how date_string could look like.
priority: The priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
indent: The indent of the item (a number between 1 and 4 where 1 is top-level).
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
item_order: The order of the task
children: The tasks child tasks (a list of task ids such as [13134,232345])
labels: The tasks labels (a list of label ids such as [2324,2525])
assigned_by_uid: The id of user who assigns current task. Makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If value is unset or invalid it will automatically be set up by your uid.
responsible_uid: The id of user who is responsible for accomplishing current task. Makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If value is unset or invalid it will automatically be set up by null.
note: Add a note directly to the task, note is a string of the content
Successful return:
HTTP 200 OK with a JSON object with task data. Example:
https://api.todoist.com/API/addItem?content=Test&project_id=22073&priority=1&token=fb5f22601ec566e48083213f7573e908a7a272e5
                {
                  "due_date": null,
                  "user_id": 1,
                  "collapsed": 0,
                  "in_history": 0,
                  "priority": 1,
                  "item_order": 5,
                  "content": "Test",
                  "indent": 1,
                  "project_id": 22073,
                  "id": 210873,
                  "checked": 0,
                  "date_string": null
                }
                
Error returns:
"ERROR_PROJECT_NOT_FOUND"
"ERROR_WRONG_DATE_SYNTAX"

/API/updateItem

Update an existing item.
Required parameters:
id: The id of the item to update
token: The user's token (received on login)
Optional parameters:
content: The text of the task
date_string: The date of the task, added in free form text. Examples of how date_string could look like.
priority: The priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
indent: The indent of the item (a number between 1 and 4 where 1 is top-level).
item_order: The order of the task
collapsed: 1 if the item should be collapsed, 0 if it should not be collapsed
children: The tasks child tasks (a list of task ids such as [13134,232345])
labels: The tasks labels (a list of label ids such as [2324,2525])
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
assigned_by_uid: The id of user who assigns current task. Makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If value is unset or invalid it will automatically be set up by your uid.
responsible_uid: The id of user who is responsible for accomplishing current task. Makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If value is unset or invalid it will automatically be set up by null.
Successful return:
HTTP 200 OK with a JSON object with the updated task data. Example:
https://api.todoist.com/API/updateItem?id=210873&content=TestHello&token=fb5f22601ec566e48083213f7573e908a7a272e5
                {
                  "due_date": null,
                  "user_id": 1,
                  "collapsed": 0,
                  "in_history": 0,
                  "priority": 1,
                  "item_order": 5,
                  "content": "TestHello",
                  "indent": 1,
                  "project_id": 22073,
                  "id": 210873,
                  "checked": 0,
                  "date_string": null
                }
                
Error returns:
"ERROR_ITEM_NOT_FOUND"

/API/updateOrders

Update the order of a project's tasks.
Required parameters:
project_id: The project of the tasks
item_id_list: A JSON list of the tasks's order, could be [3,2,9,7]
token: The user's token (received on login)
Successful return:
HTTP 200 OK with:
"ok"
Error returns:
"ERROR_PROJECT_NOT_FOUND"

/API/moveItems

Move items from one project to another.
Required parameters:
project_items: A JSON mapping telling Todoist where the items are currently found. From project_ids to item ids, could be like this {"1523":["9637423"]}, where 1523 is project_id and 9637423 is item_id.
to_project: A project_id that the items should be moved to. Could be 1245
token: The user's token (received on login)
Successful return:
HTTP 200 OK with the new counts of the projects involved, could be:
                    {"counts": {"1523": 0, "1245": 1}}
                

/API/updateRecurringDate

Update recurring dates and set them to next date regarding an item's date_string.
Required parameters:
ids: A JSON list of items that are recurring.
token: The user's token (received on login)
Optional parameters:
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
Successful return:
HTTP 200 OK with a JSON list with the updated tasks. Example:
                [{
                  "due_date": "Wed Mar  3 23:59:59 2010",
                  "collapsed": 0,
                  "labels": [],
                  "is_dst": 0,
                  "has_notifications": 0,
                  "checked": 0,
                  "indent": 1,
                  "children": null,
                  "content": "Test",
                  "user_id": 1,
                  "mm_offset": 60,
                  "in_history": 0,
                  "id": 3457537,
                  "priority": 3,
                  "item_order": 99,
                  "project_id": 455832,
                  "chains": null,
                  "date_string": "every day"
                }]
                

/API/deleteItems

Delete existing items.
Required parameters:
ids: A JSON list of ids to delete
token: The user's token (received on login)
Successful return:
HTTP 200 OK with:
"ok"

/API/completeItems

Complete items and move them to history.
Required parameters:
ids: A JSON list of ids to complete
token: The user's token (received on login)
Optional parameters:
in_history: If these tasks should be moved to history, default is 1. Setting it to 0 will not move it to history. Useful when checking off sub tasks.
Successful return:
HTTP 200 OK with:
"ok"

/API/uncompleteItems

Uncomplete items and move them to the active projects.
Required parameters:
ids: A JSON list of ids to uncomplete
token: The user's token (received on login)
Successful return:
HTTP 200 OK with:
"ok"

Notes [top]

Notes are only available for Todoist Premium users.

/API/addNote

Adds a note to an item.
Required parameters:
item_id: The id of the item
content: The content of the note
token: The user's token (received on login)
Successful return:
HTTP 200 OK with the note JSON object:
                {...}
                

/API/updateNote

Updates an existing note.
Required parameters:
note_id: The id of the note
content: The content of the note
token: The user's token (received on login)
Successful return:
HTTP 200 OK with text:
"ok"

/API/deleteNote

Delete an existing note.
Required parameters:
item_id: The id of the item (the task)
note_id: The id of the note
token: The user's token (received on login)
Successful return:
HTTP 200 OK with text:
"ok"

/API/getNotes

Returns all notes of an item.
Required parameters:
item_id: The id of the item (the task)
token: The user's token (received on login)
Successful return:
HTTP 200 OK with a JSON list of note objects:
                [{...}, ..., {...}]
                

/API/getNotesData

Returns all notes of an item and the item itself.
Required parameters:
item_id: The id of the item (the task)
token: The user's token (received on login)
Successful return:
HTTP 200 OK with a JSON list of note objects:
                {
                    "item": {},
                    "project": {},
                    "notes": [{...}, ..., {...}]
                }
                

Date query and search [top]

/API/query

Required parameters:
queries: A JSON list of queries to search. Examples of searches can be found on Todoist help
token: The user's token (received on login)
Optional parameters:
as_count: If set to 1 then no data will be returned, instead count of tasks will be returned.
js_date: If js_date is set to 1 dates will be formated as new Date("Sun Apr 29 2007 23:59:59"), otherwise they will be formatted as "Sun Apr 29 2007 23:59:59".
Successful return:
HTTP 200 OK with JSON data of tasks found:
https://api.todoist.com/API/query?queries=["2007-4-29T10:13","overdue","p1","p2"]&token=fb5f22601ec566e48083213f7573e908a7a272e5
JSON data is returned:
                    [{
                      "type": "date",
                      "query": "2007-4-29T10:13",
                      "data": [
                        [...]
                      ]
                    }, {
                      "type": "overdue",
                      "data": [...]
                    },
                    ...]
                

File uploads [top]

/API/uploadFile

The endpoint accepts two ways to upload files. The first one is convenient for classic web forms, and another one is more convenient for API clients, having nothing to do with HTML.

Required parameters:
token: The user's token (received on login)
Classic approach:
We expect the request POST data encoded as "multipart/form-data", and a "file" field. Example:
curl -F file=@example.jpg https://todoist.com/API/uploadFile?token=<token>
                        {
                            "file_name": "example.jpg",
                            "file_size": 85665,
                            "file_type": "image/jpeg",
                            "file_url": "https://xxxxxxx.cloudfront.net/xxxxxxxxxxxxxxxxxxxxx/as/baby.jpg",
                            "tn_l": [
                                "https://xxxxxx.cloudfront.net/tn_l_xxxxxxxxxxxxxxxxxxxxx.jpg",
                                400, 309
                            ],
                            "tn_m": [
                                "https://xxxxxx.cloudfront.net/tn_m_xxxxxxxxxxxxxxxxxxxxx.jpg",
                                288, 222
                            ],
                            "tn_s": [
                                "https://xxxxxx.cloudfront.net/tn_s_xxxxxxxxxxxxxxxxxxxxxx.jpg",
                                96, 74
                            ]
                        }
                    
API approach:
We expect the request having the "file_name" GET attribute (or, alternatively, the "X-File-Name" HTTP header) and the raw file content in POST body. Example:
curl --data-binary @example.jpg https://todoist.com/API/uploadFile?token=<token>&file_name=example.jpg
                        {
                            "file_name": "example.jpg",
                            "file_size": 85665,
                            "file_type": "image/jpeg",
                            "file_url": "https://xxxxxxx.cloudfront.net/xxxxxxxxxxxxxxxxxxxxx/as/baby.jpg",
                            "tn_l": [
                                "https://xxxxxx.cloudfront.net/tn_l_xxxxxxxxxxxxxxxxxxxxx.jpg",
                                400, 309
                            ],
                            "tn_m": [
                                "https://xxxxxx.cloudfront.net/tn_m_xxxxxxxxxxxxxxxxxxxxx.jpg",
                                288, 222
                            ],
                            "tn_s": [
                                "https://xxxxxx.cloudfront.net/tn_s_xxxxxxxxxxxxxxxxxxxxxx.jpg",
                                96, 74
                            ]
                        }
                    
Successful return:
HTTP 200 OK with JSON data of file data, suitable to be passed as a file_attachment attribute to note_add or note_update API call of the Sync API.

Live Notifications [top]

Live notification structure

Every live notification has following fields. Some of them are common for all types of notifications, whereas some others depend on notification type.

created
Required. Live notification creation date. Integer representing a timestamps since epoch
from_uid
Required. The id of user who initiated this live notification
notification_key
Required. Unique notification key
notification_type
Required. Type of notification. Different notification type define different extra fields which are described below
seq_no
Required. Notification sequence number
from_user
Optional. User data, useful on share_invitation_sent
project_name
Optional. The project name, useful for share_invitation_* where you may not have the project in the local model
invitation_secret
Optional. Useful for accepting/rejecting invitations

Types of live notifications

This is the list of notifications which can be issued by the system.

share_invitation_sent
Sent to sharing invitation receiver. When the invitation is accepted/rejected, the state changes. State is initially non-existent.
{
    "created": 1377639720,
    "from_uid": 123,
    "invitation_id": 123,
    "invitation_secret": 456,
    "notification_key": "...",
    "notification_type": "...",
    "seq_no": "...",
    "state": "accepted"
}
share_invitation_accepted
Sent to sharing invitation sender, when the receiver accepts the invitation
{
    "created": 1377639720,
    "from_uid": 123,
    "invitation_id": 456,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 123,
    "seq_no": "..."
}
share_invitation_rejected
Sent to sharing invitation sender, when the receiver rejects the invitation
{
    "created": 1377639720,
    "from_uid": 123,
    "invitation_id": 456,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 123,
    "reject_email": "foo@example.com",
    "seq_no": "..."
}
user_left_project
Sent to everyone when somebody leaves the project
{
    "created": 1377639720,
    "from_uid": 123,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 123,
    "seq_no": "..."
}
user_removed_from_project
Sent to everyone when a person removes somebody from the project. removed_name and removed_uid are added as extras.
{
    "created": 1377639720,
    "from_uid": 123,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 123,
    "removed_name": "Bruce Wayne",
    "removed_uid": 1212,
    "seq_no": "..."
}
item_assigned
This notification is sent to user who is responsible for the task. Optionally it's also sent to the user who created the task initially, if the assigner and the task creator is not the same person.
{
    "assigned_by_uid": 789,
    "created": 1377639720,
    "from_uid": 123,
    "item_content": "...",
    "item_id": 123,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 456,
    "responsible_uid": 123,
    "seq_no": "..."
}
item_completed
This notification is sent to user who assigned the task when the task is completed. Optionally it's also sent to the user who is responsible for this task, if the responsible and the user who completed the task is not the same person.
{
    "assigned_by_uid": 789,
    "created": 1377639720,
    "from_uid": 123,
    "item_content": "...",
    "item_id": 123,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 456,
    "responsible_uid": 123,
    "seq_no": "..."
}
item_uncompleted
This notification is sent to user who assigned the task when the task is uncompleted. Optionally it's also sent to the user who is responsible for this task, if the responsible and the user who completed the task is not the same person.
{
    "assigned_by": "user",
    "created": 1377639720,
    "from_uid": 123,
    "item": 123,
    "item_content": "...",
    "notification_key": "...",
    "notification_type": "...",
    "project": 456,
    "responsible": "user",
    "seq_no": "..."
}
note_added
This notification is sent to all members of the shared project, whenever someone adds a note to the task.
{
    "created": 1377639720,
    "from_uid": 123,
    "item_id": 123,
    "note_content": "...",
    "note_id": 789,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 456,
    "seq_no": "..."
}
biz_policy_disallowed_invitation
This notification is sent to you when you try to share a project with someone outside of your business account, but the business account policy disallows this action.
{
    "created": 1377639720,
    "email": "...",
    "from_uid": null,
    "notification_key": "...",
    "notification_type": "...",
    "project_id": 123,
    "seq_no": "...",
    "user": {
        "email": "...",
        "full_name": "...",
        "id": "...",
        "image_id": "..."
    }
}
biz_policy_rejected_invitation
This notification is sent to you when you try to accept the invitation to a shared project from someone outside of your business account, but the business account policy disallows this action.
{
    "created": 1377639720,
    "from_uid": null,
    "inviter_id": 123,
    "notification_key": "...",
    "notification_type": "...",
    "seq_no": "...",
    "user": {
        "email": "...",
        "full_name": "...",
        "id": "...",
        "image_id": "..."
    }
}
biz_trial_will_end
The notification is sent to all business account administrators three days before the trial period of a subscription is scheduled to end.
quantity
The number of users under the control of the business account
plan
Tariff plan name. Valid values are "business_monthly" and "business_yearly"
active_until
The timestamp when the business account will be disabled. The value may not match the business account subscription end date, as we give some extra days (up to two weeks) to pay the invoice
{
    "active_until": 1399299727,
    "created": 1377639720,
    "from_uid": null,
    "notification_key": "...",
    "notification_type": "...",
    "plan": "business_monthly",
    "quantity": 10,
    "seq_no": "..."
}
biz_payment_failed
The notification is sent to all business account administrators whenever an invoice attempts to be paid, and the payment fails. This can occur either due to a declined payment, or because the customer has no active card. A particular case of note is that if a customer with no active card reaches the end of its free trial.
quantity
The number of users under the control of the business account
plan
Tariff plan name. Valid values are "business_monthly" and "business_yearly"
active_until
The timestamp when the business account will be disabled. The value may not match the business account subscription end date, as we give some extra days (up to two weeks) to pay the invoice
amount_due
Invoice amount. Integer value in 0.01 of currency
attempt_count
Number of automatic payment attempts made for this invoice
currency
Currency value. Three-letter ISO currency code representing the currency in which the charge was made.
description
Invoice description
next_payment_attempt
Timestamp value
{
    "active_until": 1399299727,
    "amount_due": 600,
    "attempt_count": 1,
    "created": 1377639720,
    "currency": "usd",
    "description": "2 x Subscription to Monthly ($3.00/month)",
    "from_uid": null,
    "next_payment_attempt": 1399299735,
    "notification_key": "...",
    "notification_type": "...",
    "plan": "business_monthly",
    "quantity": 10,
    "seq_no": "..."
}
biz_account_disabled
The notification is sent to all business account administrators when the account is disabled.
quantity
The number of users under the control of the business account
plan
Tariff plan name. Valid values are "business_monthly" and "business_yearly"
active_until
The timestamp when the business account will be disabled. The value may not match the business account subscription end date, as we give some extra days (up to two weeks) to pay the invoice
{
    "active_until": 1399299727,
    "created": 1377639720,
    "from_uid": null,
    "notification_key": "...",
    "notification_type": "...",
    "plan": "business_monthly",
    "quantity": 10,
    "seq_no": "..."
}
biz_invitation_created
The notification is sent to an invitee, when one of business account administrators invites this user to the business account.
state
Invitation state. Initially "invited", can change the state to "accepted" or "rejected"
invitation_secret
Invitation secret. Should be used to accept or reject invitation. The acceptance URL is "https://todoist.com/API/Business/Users/acceptInvitation?secret=invitation_secret". To reject the invitation, follow the URL "https://todoist.com/API/Business/Users/rejectInvitation?secret=invitation_secret"
invitation_message
Invitation message
account_name
Business account (company) name
{
    "account_name": "Foo Inc",
    "created": 1377639720,
    "from_uid": 123,
    "from_user": {
        "email": "...",
        "full_name": "...",
        "id": "...",
        "image_id": "..."
    },
    "invitation_id": 123,
    "invitation_message": "Welcome to our team!",
    "invitation_secret": "15496905a43161c34ebe763482ae3c50",
    "notification_key": "...",
    "notification_type": "...",
    "seq_no": "..."
}
biz_invitation_accepted
The notification is sent to an inviter, when the invitation is accepted.
{
    "created": 1377639720,
    "from_uid": 123,
    "from_user": {
        "account_name": "...",
        "email": "...",
        "full_name": "...",
        "id": "...",
        "image_id": "..."
    },
    "invitation_id": 123,
    "notification_key": "...",
    "notification_type": "...",
    "seq_no": "..."
}
biz_invitation_rejected
The notification is sent to an inviter, when the invitation is rejected.
{
    "created": 1377639720,
    "from_uid": 123,
    "from_user": {
        "account_name": "...",
        "email": "...",
        "full_name": "...",
        "id": "...",
        "image_id": "..."
    },
    "invitation_id": 123,
    "notification_key": "...",
    "notification_type": "...",
    "seq_no": "..."
}

Live Notifications Settings [top]

/API/getNotificationSettings

Required parameters:
token: The user's token (received on login)
Successful return:
HTTP 200 OK with JSON data:
https://api.todoist.com/API/getNotificationSettings?api_token=f3ecac31a53f9d0448e4f1b273d8e7f118500a7d
JSON data is returned:
                {
                    "user_removed_from_project": {
                        "notify_push": false,
                        "notify_email": false
                    },
                    "item_completed": {
                        "notify_push": true,
                        "notify_email": true
                    },
                    "note_added": {
                        "notify_push": false,
                        "notify_email": false
                    },
                    "share_invitation_rejected": {
                        "notify_push": true,
                        "notify_email": true
                    },
                    "item_uncompleted": {
                        "notify_push": true,
                        "notify_email": true
                    },
                    "item_assigned": {
                        "notify_push": false,
                        "notify_email": false
                    },
                    "share_invitation_accepted": {
                        "notify_push": false,
                        "notify_email": false
                    },
                    "user_left_project": {
                        "notify_push": true,
                        "notify_email": true
                    }
                }
                

/API/updateNotificationSetting

Required parameters:
token: The user's token (received on login)
notification_type: The notification type (could be user_left_project)
service: Service type (could be email or push)
dont_notify: Should we notify on this service? (could be 1 or 0)
Successful return:
HTTP 200 OK with text:
"ok"