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 = 'http://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.com.
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.

notifo: User's Notifo account. Empty string ("") if not set.
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/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
timezone: User's timezone (check API call /API/getTimezones)
Optional parameters:
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:
"ALREADY_REGISTRED"
"TOO_SHORT_PASSWORD"
"INVALID_EMAIL"
"INVALID_TIMEZONE"
"INVALID_FULL_NAME"
"UNKNOWN_ERROR"

/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
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,!p1)
Successful return:
HTTP 200 OK with a JSON object with user data: 
                    {"email": "...", "token": ..., ...}
Error returns:
"ERROR_PASSWORD_TOO_SHORT"
"ERROR_EMAIL_FOUND"

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": 13,
              "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?
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": 4,
                      "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": 1L,
                      "name": "Test project",
                      "color": 1L,
                      "collapsed": 0L,
                      "item_order": 1L,
                      "indent": 1L,
                      "cache_count": 4L,
                      "id": 22073L
                    }
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/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
label: Filter the tasks by label (could be home)
interval: Restrict time range, default is past 2 weeks, can be following:
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/getCompletedItems

Returns a project's completed items (tasks) - the tasks that are in history.
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": 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:
http://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:
project_id: The id of the project to add to
content: The text of the task
token: The user's token (received on login)
Optional parameters:
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])
Successful return:
HTTP 200 OK with a JSON object with task data. Example:
http://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".
Successful return:
HTTP 200 OK with a JSON object with the updated task data. Example:
http://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 delete
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 delete
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 tem.
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:
                [{...}, ..., {...}]

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:
http://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": [...]
                    }, 
                    ...]