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

Solving cross domain security policy

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: The response data will look like this (callbackFunction will be called):

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", "twitter": "", "api_token": "d18a76ab310947100kc60fe9b3cdc466515bb3a1", "time_format": 0, "sort_order": 0, "full_name": "Joh Doe", "mobile_number": "", "mobile_host": "", "timezone": "Europe/Copenhagen", "jabber": "john@doe.com", "id": 1, "date_format": 1, "premium_until": "Sat Sep 22 13:15:03 2018", "tz_offset": ["+01:00", 1, 0, 0], "msn": "amix_bih@msn.com", "default_reminder": "no_default", "email": "john@doe.com"}

What does the different properties mean?

email: User's email.

full_name: User's real name.

id: User's unique id.

api_token: User's token (that should be used to call the other methods).

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.

twitter: User's Twitter account. Empty string ("") if not set.

jabber: User's Jabber account. Empty string ("") if not set.

msn: User's MSN 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 info:
{"email": "...", "token": ..., ...}

Error returns:

"LOGIN_ERROR"

/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/getTimezones)

Successful return:

HTTP 200 OK with a JSON object with user info:
{"email": "...", "token": ..., ...}

Error returns:

"ALREADY_REGISTRED"

"TOO_SHORT_PASSWORD"

"INVALID_EMAIL"

"INVALID_TIMEZONE"

"INVALID_FULL_NAME"

"UNKNOWN_ERROR"

/API/updateUser should be HTTPS

You can just update full_name if you like, don't send paramters that you don't want to change.

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)

Successful return:

HTTP 200 OK with a JSON object with user info:
{"email": "...", "token": ..., ...}

Error returns:

"ERROR_PASSWORD_TOO_SHORT"

"ERROR_EMAIL_FOUND"

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": "#ff8581", "collapsed": 0, "item_order": 1, "cache_count": 13, "indent": 1, "id": 455831}

What does the different properties mean?

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

indent: What indention level does the project have? It ranges from 1 to 4 (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.

/API/getProjects

Returns all os 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 information 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 info
{"user_id": 1L, "name": "Test project", "color": 1L, "collapsed": 0L, "item_order": 1L, "indent": 1L, "cache_count": 4L, "id": 22073L}

/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 new project

order: The order of the new project

Successful return:

HTTP 200 OK with a JSON object with project info:
{"name": "...", "user_id": ..., ..., "collapsed": 0L, "id": 22000}

Error returns:

"ERROR_NAME_IS_EMPTY"

/API/updateProject

Update an existing project.

Required parameters:

proejct_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: New indent of the project

Successful return:

HTTP 200 OK with a JSON object with project info:
{"name": "...", "user_id": ..., ..., "collapsed": 0L, "id": 22000}

Error returns:

"ERROR_PROJECT_NOT_FOUND"

/API/deleteProject

Delete an existing project.

Required parameters:

proejct_id: The id of the project to update

token: The user's token (received on login)

Successful return:

HTTP 200 OK with text:
"ok"

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

/API/getLabels

Returns all of user's labels.

Required parameters:

proejct_id: The id of the project to update

token: The user's token (received on login)

/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 text:
"ok"

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

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

What does the different properties mean?

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 true this date will be formated as new Date("Sun Apr 29 23:59:59 2007"), otherwise it will be formatted as "Sun Apr 29 23:59:59 2007". 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: What indention level does the item have? It ranges from 1 to 5 (1 is top level).

/API/getUncompletedItems

Returns a project's uncompleted items (tasks).

Required parameters:

proejct_id: The id of the project to update

token: The user's token (received on login)

Successful return:

HTTP 200 OK with a JSON object with user info:
[{"due_date": new Date("Sun Apr 29 23:59:59 2007"), "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": ""},
...]

/API/getCompletedItems

Returns a project's completed items (tasks) - the tasks that are in history.

Required parameters:

proejct_id: The id of the project to update

token: The user's token (received on login)

Successful return:

HTTP 200 OK with a JSON object with user info:
[{"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": ""}
...]

/API/getItemsById

Required parameters:

ids: A JSON list of ids to fetch

token: The user's token (received on login)

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:

proejct_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 - 1 for very urgent and 4 for natural).

Successful return:

HTTP 200 OK with a JSON object with task info. 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}

/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 - 1 for very urgent and 4 for natural).

indent: The indent of the task

item_order: The order of the task

Successful return:

HTTP 200 OK with a JSON object with the updated task info. 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}

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

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

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"

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

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