I keep track of tasks using Todoist, a cross-platform to-do list tool. It’s flexible without making simple things hard, which I appreciate1. For example, adding a task with a deadline and a tag is as simple as clicking the plus button and typing “Call landlord @telephone today”.
Since I cannot leave well enough alone, I’ve been playing with the Todoist API. I don’t have any big complaints; however, there are a few edge cases not covered in the documentation that I had to figure out myself. To save you the trouble, I present a guide to the unexplained parts of Todoist.
Recurring Tasks
The API actually has a specific piece of metadata for recurring tasks,
date_string,
something I didn’t realize until I looked more closely at the requests when
writing this post.
I’m a bit unsure about how the due dates workâthey don’t seem to work consistently. It seems like sometimes the completed task has the old due date and sometimes it has the date it was completed. No idea what’s up with that.
{
"event_data": {
"assigned_by_uid": 1855589,
"checked": 0,
"collapsed": 0,
"content": "Wash dishes",
"date_added": "Sat 04 Jul 2015 06: 56: 47 +0000",
"date_lang": "en",
"date_string": "every day",
"due_date": "Wed 18 Nov 2015 05: 59: 59 +0000",
"due_date_utc": "Wed 18 Nov 2015 05: 59: 59 +0000",
"id": 9381128,
"in_history": 0,
"indent": 2,
"is_archived": 0,
"is_deleted": 0,
"item_order": 3,
"labels": [
222194
],
"priority": 1,
"project_id": 146542931,
"responsible_uid": null,
"sync_id": null,
"user_id": 1855589
},
"event_name": "item: completed",
"user_id": 1855589
}
{
"event_data": {
"assigned_by_uid": 1855589,
"checked": 0,
"collapsed": 0,
"content": "Wash dishes",
"date_added": "Sat 04 Jul 2015 06: 56: 47 +0000",
"date_lang": "en",
"date_string": "every day",
"due_date": "Wed 18 Nov 2015 05: 59: 59 +0000",
"due_date_utc": "Wed 18 Nov 2015 05: 59: 59 +0000",
"id": 9381128,
"in_history": 0,
"indent": 2,
"is_archived": 0,
"is_deleted": 0,
"item_order": 3,
"labels": [
222194
],
"priority": 1,
"project_id": 146542931,
"responsible_uid": null,
"sync_id": null,
"user_id": 1855589
},
"event_name": "item: updated",
"user_id": 1855589
}
Completed tasks
If you use the sync API,
you can check in_history to find out if a task is completed.
If you use the webhooks API,
you have to check that you’ve received a item:completed event.
If you want to be thorough,
you actually have to check that there is an item:completed event
that isn’t negated by any item:uncompleted events.
Localization of dates
You can enter dates as phrases, like ‘everyday’. But if you switch languages, how does Todoist handle it?
Rather well, actually.
It stores the date as-is,
but also stores the language in a separate variable, date_lang.
{
"date_lang": "de",
"date_string": "Dez 5",
"due_date": "Sun 06 Dec 2015 05:59:59 +0000",
"due_date_utc": "Sun 06 Dec 2015 05:59:59 +0000"
}
I’ve never actually used this feature from the API, but it’s neat to see a product that handles multiple languages so well.
More examples of notifications
Note without file
The most common kind of note, but not included in the documentation.
{
"event_data": {
"content": "Milk \nButter \nEggs ",
"file_attachment": null,
"id": 5920490,
"is_archived": 0,
"is_deleted": 0,
"item_id": 26552983,
"posted": "Fri 04 Dec 2015 22:49:46 +0000",
"posted_uid": 1855589,
"project_id": 128501470,
"uids_to_notify": []
},
"event_name": "note:added",
"user_id": 1855589
}
Archived project
{
"event_data": {
"archived_date": null,
"archived_timestamp": 0,
"collapsed": 0,
"color": 9,
"id": 5920490,
"indent": 2,
"is_archived": 0,
"is_deleted": 0,
"item_order": 9,
"name": "Shopping",
"user_id": 1855589
},
"event_name": "project:archived",
"user_id": 1855589
}
Postponing a task
{
"event_data": {
"assigned_by_uid": 1855589,
"checked": 0,
"collapsed": 0,
"content": "Return books",
"date_added": "Mon 30 Nov 2015 09:02:20 +0000",
"date_lang": "de",
"date_string": "Dez 5",
"due_date": "Sun 06 Dec 2015 05:59:59 +0000",
"due_date_utc": "Sun 06 Dec 2015 05:59:59 +0000",
"id": 5920490,
"in_history": 0,
"indent": 1,
"is_archived": 0,
"is_deleted": 0,
"item_order": 1,
"labels": [],
"priority": 1,
"project_id": 146466214,
"responsible_uid": null,
"sync_id": null,
"user_id": 4810225
},
"event_name": "item:added",
"user_id": 1855589
}
{
"event_data": {
"assigned_by_uid": 1855589,
"checked": 0,
"collapsed": 0,
"content": "Return books",
"date_added": "Mon 30 Nov 2015 09:02:20 +0000",
"date_lang": "de",
"date_string": "7 Dez.",
"due_date": "Tue 08 Dec 2015 05:59:59 +0000",
"due_date_utc": "Tue 08 Dec 2015 05:59:59 +0000",
"id": 5920490,
"in_history": 0,
"indent": 1,
"is_archived": 0,
"is_deleted": 0,
"item_order": 1,
"labels": [],
"priority": 1,
"project_id": 146466214,
"responsible_uid": null,
"sync_id": null,
"user_id": 4810225
},
"event_name": "item:updated",
"user_id": 1855589
}
{
"event_data": {
"assigned_by_uid": 1855589,
"checked": 0,
"collapsed": 0,
"content": "Return books",
"date_added": "Mon 30 Nov 2015 09:02:20 +0000",
"date_lang": "de",
"date_string": "Dez 14",
"due_date": "Tue 15 Dec 2015 05:59:59 +0000",
"due_date_utc": "Tue 15 Dec 2015 05:59:59 +0000",
"id": 5920490,
"in_history": 0,
"indent": 1,
"is_archived": 0,
"is_deleted": 0,
"item_order": 1,
"labels": [],
"priority": 1,
"project_id": 146466214,
"responsible_uid": null,
"sync_id": null,
"user_id": 4810225
},
"event_name": "item:updated",
"user_id": 1855589
}
-
That being said, if you’re looking for a to-do app, don’t stop with Todoist. The field of to-do apps is so crowded that there are a dozen plausible alternatives, each a little different. There might well be an equally great alternative that happens to fit you better. I’ve heard great things about OmniFocus, for example. ↩