This API is depreciated. Please upgrade to our new improved 3.0 API. This API will continue to work for some time, but it is no longer supported and it will eventually go away.

Developer's API Documentation - Tasks

The Toodledo API makes it easy for developers to interact with their tasks and make new and interesting applications.

The Toodledo API uses a REST interface. REST is a simple format that allows you to make queries by constructing a URL and making an HTTP GET or POST. The server responds with an XML document containing the information that you requested.

The API documentation is split between these three pages:

Authentication and General API Tasks API Notebook API

Retrieving Tasks

The "getTasks" API call will return a list of the tasks that match your search parameters. The following search parameters may be set.

title : A text string up to 255 characters. Boolean operators do not work yet, so your search will be for a single phrase. Please encode the & character as %26 and the ; character as %3B.
tag : A text string up to 64 characters. Please encode the & character as %26 and the ; character as %3B.
folder : The id number of the folder as returned from the "getFolders" API call. 0 is a special number that returns tasks without a set folder.
context : The id number of the context as returned from the "getContexts" API call. 0 is a special number that returns tasks without a set context.
goal : The id number of the goal as returned from the "getGoals" API call. 0 is a special number that returns tasks without a set goal.
priority : An integer that represents the priority.

-1 = Negative
0 = Low
1 = Medium
2 = High
3 = Top

repeat : An integer that represents how the tasks repeats.

0 = No Repeat
1 = Weekly
2 = Monthly
3 = Yearly
4 = Daily
5 = Biweekly
6 = Bimonthly
7 = Semiannually
8 = Quarterly
9 = With Parent

status : An integer that represents the status of the task.

0 = None
1 = Next Action
2 = Active
3 = Planning
4 = Delegated
5 = Waiting
6 = Hold
7 = Postponed
8 = Someday
9 = Canceled
10 = Reference

parent : This is used by accounts with a Subscription that have access to subtasks. Set this to the id number of the parent task and you will get its subtasks. The default is 0, which is a special number that returns tasks that do not have a parent.
shorter : An integer representing minutes. This is used for finding tasks with a duration that is shorter than the specified number of minutes.
longer : An integer representing minutes. This is used for finding tasks with a duration that is longer than the specified number of minutes.
before : A date formated as YYYY-MM-DD. Used to find tasks with due-dates before this date.
after : A date formated as YYYY-MM-DD. Used to find tasks with due-dates after this date.
startbefore : A date formated as YYYY-MM-DD. Used to find tasks with start-dates before this date.
startafter : A date formated as YYYY-MM-DD. Used to find tasks with start-dates after this date.
modbefore : A date-time formated as YYYY-MM-DD HH:MM:SS. Used to find tasks with a modified date and time before this date and time.
modafter : A date-time formated as YYYY-MM-DD HH:MM:SS or a unix timestamp. Used to find tasks with a modified date and time after this date and time.
compbefore : A date formated as YYYY-MM-DD. Used to find tasks with a completed date before this date.
compafter : A date formated as YYYY-MM-DD. Used to find tasks with a completed date after this date.
notcomp : Set to 1 to omit completed tasks. Omit variable, or set to 0 to retrieve both completed and uncompleted tasks.
star : A boolean (0 or 1) that indicates if the task has a star or not.
id : The id number of the task that you want to fetch. This is useful if you already know the id number and only need to fetch the one task.
start : The number of records that you want to skip before printing results. Use this in combination with "end" if you want to paginate your results. The default value is 0.
end : The number of records to go through until output is stopped. Use this in combination with "start" if you want to paginate your results. The default value is 1000. The maximum number of tasks that can be returned at a time is 1000, so if end>start+1000, you may get fewer results that you are expecting.
unix : If this is set to 1, all dates will be returned as unix timestamps instead of human readable strings.

http://api.toodledo.com/api.php?method=getTasks;key=YourKey;shorter=130;
longer=10;priority=2;end=2

This returns a list of tasks that might look something like this.

<tasks num="2" total="45" start="0" end="2">
	<task>
		<id>1234</id>
		<parent>1122</parent>
		<children>0</children>
		<title>Buy Milk</title>
		<tag>After work</tag>
		<folder>123</folder>
		<context id="123">Home</context>
		<goal id="123">Get a Raise</goal>
		<added>2006-01-23</added>
		<modified>2006-01-25 05:12:45</modified>
		<startdate></startdate>
		<duedate modifier=""></duedate>
		<duetime>2:00pm</duetime>
		<starttime>1:00pm</starttime>
		<reminder>60</reminder>
		<completed></completed>
		<repeat>1</repeat>
		<rep_advanced></rep_advanced>
		<status>4</status>
		<star>0</star>
		<priority>2</priority>
		<length>20</length>
		<timer onfor="0">0</timer>
		<note></note>
	</task>
	<task>
		<id>1235</id>
		<parent>0</parent>
		<children>2</children>
		<title>Fix flat tire</title>
		<tag>before work</tag>
		<folder>456</folder>
		<context id="0"></context>
		<goal id="0"></goal>
		<added>2006-01-23</added>
		<modified>2006-01-23 15:45:55</modified>
		<startdate>2024-04-19</startdate>
		<duedate modifier="=">2024-04-19</duedate>
		<duetime>9:45am</duetime>
		<starttime>4:45am</starttime>
		<reminder></reminder>
		<completed>2024-04-19</completed>
		<repeat>50</repeat>
		<rep_advanced>Every Monday</rep_advanced>
		<status>2</status>
		<star>1</star>
		<priority>2</priority>
		<length>120</length>
		<timer onfor="123">600</timer>
		<note>Use the car jack</note>
	</task>
</tasks>

Most of the returned values should be self explanatory with a few exceptions. The value of the "repeat" field may have some special values. Values 0-9 will match the values listed above, but it can also have the value of 50, which indicates that the task uses advanced repeating. If this is the case, you will need to look at the "rep_advanced" field. Additionally, if the task is set to repeat from the completion date (instead of the original due-date), the repeat value will be incremented by 100. For example, a repeat value of 2 means repeat monthly from the due-date and a value of 102 means repeat monthly from the completion date.

The timer field also needs a little explanation. The value in the timer field indicates the number of seconds that have elapsed for the timer not including the current session. If the timer is currently on, the "onfor" value will contain a unix timestamp indicating the last time that the timer was started. Therefore, if the timer is currently on, you will need to calculate the elapsed time when you present it to the user. This calculation is: Total Time=timer+(now-onfor). Where "now" is a unix timestamp for the current time in Toodledo's timezone (which can be found with the "getServerInfo" API call).

"num" is the number of tasks in the current result set. "total" is the total number of tasks that would match your query if you did not use the "start" and "end" paramaters to paginate your results.

Adding Tasks

You can easily add a task to your list with the "addTask" API call. The title field is required, but all other fields are optional.

title : A text string up to 255 characters. Please encode the & character as %26 and the ; character as %3B.
tag : A text string up to 64 characters. Please encode the & character as %26 and the ; character as %3B.
folder : The id number of the folder as returned from the "getFolders" API call. Omit this field or set it to 0 to leave the task unassigned to a folder.
context : The id number of the context as returned from the "getContexts" API call. Omit this field or set it to 0 to leave the task unassigned to a context.
goal : The id number of the goal as returned from the "getGoals" API call. Omit this field or set it to 0 to leave the task unassigned to a goal.
parent : This is used by accounts with a Subscription that have access to subtasks. To create a subtask, set this to the id number of the parent task. The default is 0, which creates a normal task.
duedate : A date formated as YYYY-MM-DD or a unix timestamp with an optional modifier attached to the front. Examples: "2007-01-23" , "=2007-01-23" , ">2007-01-23".
startdate : A start date formated as YYYY-MM-DD or as a unix timestamp.
duetime : A date formated as HH:MM MM. Examples: 12:34 am, 4:56 pm.
starttime : A date formated as HH:MM MM. Examples: 12:34 am, 4:56 pm.
reminder : An integer that represents the number of minutes prior to the duedate/time that a reminder will be sent. Set it to 0 for no reminder. Values will be constrained to this list of valid numbers (0, 15, 30, 45, 60, 90, 120, 180, 240, 1440, 2880, 4320, 5760, 7200, 8640, 10080, 20160, 43200). Additionally, if the user does not have a Subscription, the only valid number is 60. If you submit an invalid number, it will be rounded up or down to a valid value.
repeat : An integer that represents how the tasks will repeat. By default, a task will repeat from the due-date. To set a task to repeat from the completion date, add 100 to any of the values below.

0 = No Repeat
1 = Weekly
2 = Monthly
3 = Yearly
4 = Daily
5 = Biweekly
6 = Bimonthly
7 = Semiannually
8 = Quarterly
9 = With Parent
50 = Use Advanced Options (see below)

rep_advanced : Used in combination with repeat=50 or repeat=150. A string indicating how you would like the task to repeat. For example: "Every Monday".
status : An integer that represents the status of the task.

0 = None
1 = Next Action
2 = Active
3 = Planning
4 = Delegated
5 = Waiting
6 = Hold
7 = Postponed
8 = Someday
9 = Canceled
10 = Reference

length : An integer representing the number of minutes that the task will take to complete.
priority : An integer that represents the priority.

-1 = Negative
0 = Low
1 = Medium
2 = High
3 = Top

star : A boolean (0 or 1) that indicates if the task has a star or not.
note : A text string. Please encode the & character as %26 and the ; character as %3B.

http://api.toodledo.com/api.php?method=addTask;key=YourKey;
title=new years;priority=1;repeat=0;length=30;duedate=2010-01-01

If the add was successful the id number of the new task will be returned.

<added>12345</added>

Editing Tasks

Edit a task using the "editTask" API call. The task id is required and can be found from the getTasks or addTask API calls. Omit any fields that you do not wish to set.

id : The id number of the task to edit.
title : A text string up to 255 characters representing the name of the task. Please encode the & character as %26 and the ; character as %3B.
tag : A text string up to 64 characters. Please encode the & character as %26 and the ; character as %3B.
folder : The id number of the folder (as returned from addFolder or getFolders). A value of 0 will set the task to "No Folder".
context : The id number of the context (as returned from getContexts). A value of 0 will set the task to "No Context".
goal : The id number of the goal (as returned from getGoals). A value of 0 will set the task to "No Goal".
timer : Set to 1 or 0 to turn the timer on or off.
timerval : Set to the number of seconds elapsed for the timer.
parent : This is used by accounts with a Subscription that have access to subtasks. To create a subtask, set this to the id number of the parent task. Set it to 0 to turn a subtask back into a task.
completed : A boolean value (0 or 1) that describes if this task is completed or not.
completedon : A date formated as YYYY-MM-DD or a unix timestamp that indicates when the task was completed. The default value is the current day. This value is ignored if completed=0.
reschedule : A boolean (0 or 1) that tells Toodledo if you want us to automatically reschedule repeating tasks. The default is 0, which means that you are responsible for rescheduling repeating tasks.
duedate : A date formated as YYYY-MM-DD or a unix timestamp with an optional modifier attached to the front. Examples: "2007-01-23" , "=2007-01-23" , ">2007-01-23". To unset the date, set it to '0000-00-00'.
startdate : A start date formated as YYYY-MM-DD or a unix timestamp. To unset the date, set it to '0000-00-00'.
duetime : A date formated as HH:MM MM. Examples: 12:34 am, 4:56 pm. To unset the value, set it to 0.
starttime : A date formated as HH:MM MM. Examples: 12:34 am, 4:56 pm. To unset the value, set it to 0.
reminder : An integer that represents the number of minutes prior to the duedate/time that a reminder will be sent. Set it to 0 for no reminder. Values will be constrained to this list of valid numbers (0, 15, 30, 45, 60, 90, 120, 180, 240, 1440, 2880, 4320, 5760, 7200, 8640, 10080, 20160, 43200). Additionally, if the user does not have a Subscription, the only valid number is 60. If you submit an invalid number, it will be rounded up or down to a valid value.
repeat : An integer that represents how the tasks will repeat. By default, a task will repeat from the due-date. To set a task to repeat from the completion date, add 100 to any of the values below.

0 = No Repeat
1 = Weekly
2 = Monthly
3 = Yearly
4 = Daily
5 = Biweekly
6 = Bimonthly
7 = Semiannually
8 = Quarterly
9 = With Parent
50 = Use Advanced Options (see below)

rep_advanced : Used in combination with repeat=50 or repeat=150. A string indicating how you would like the task to repeat. For example: "Every Monday".
status : An integer that represents the status of the task.

0 = None
1 = Next Action
2 = Active
3 = Planning
4 = Delegated
5 = Waiting
6 = Hold
7 = Postponed
8 = Someday
9 = Canceled
10 = Reference

length : An integer representing the number of minutes that the task will take to complete.
priority : An integer that represents the priority.

-1 = Negative
0 = Low
1 = Medium
2 = High
3 = Top

star : A boolean (0 or 1) that indicates if the task has a star or not.
note : A text string. Please encode the & character as %26 and the ; character as %3B.

http://api.toodledo.com/api.php?method=editTask;key=YourKey;
id=12345;title=MyTask;completed=1;folder=123

If the edit was successful you will get the following message.

<success>1</success>

Deleting Tasks

The "deleteTask" API call will allow you to permanently delete a task. For tasks that you want available in the history section, or for tasks that you want to continue to repeat, you should not use this method. Instead, you should edit the task and mark it as completed.

id : The id number of the task to delete.

http://api.toodledo.com/api.php?method=deleteTask;key=YourKey;id=12345;

If the delete was successful you will get the following message.

<success>1</success>

Get Deleted Tasks

The "getDeleted" API call will enable you to detect when a task was deleted on Toodledo, so you can also delete the task from your application.

after : A date-time formated as YYYY-MM-DD HH:MM:SS or a unix timestamp. Used to find tasks that were deleted after this date and time.

http://api.toodledo.com/api.php?method=getDeleted;key=YourKey;after=2008-01-25 05:12:45

This returns a list of id numbers and datetime stamps.

<deleted>
	<task>
	<id>12345</id>
	<stamp>2008-02-25 07:46:42</stamp>
	</task>
	<task>
	<id>67890</id>
	<stamp>2008-03-12 14:11:12</stamp>
	</task>
</deleted>