The (un)official Todoist javascript API library


The (un)official Todoist javascript API library

A javascript client for Todoist Sync API with full support of endpoint resources. This is an adaptation from Todoist official Python lib.

How to start

install the package npm install todoist-js --save into your project


import the API

import TodoistAPI from 'todoist-js'

Create an instance providing an access token (how to get an access token?)

const todoist = new TodoistAPI('xxxxxxxxxx');

Get productivity stats

todoist.completed.get_stats().then(stats => {

🚀 You can see full list of capabilities in action into tests folder

Try out the lib by cloning this Runkit notebook

Implementation opportunities

  • Web apps or sites.
  • Web plugins for content managers like Wordpress, Joomla, etc.
  • Browsers add-ons.
  • Mobile world with hybrid apps frameworks like react-native, Ionic and others.
  • Node.js on server side and universal javascript apps.
  • Web components for libs like Reactjs, Angular and more.
  • Integration with desktop applications, applets, widgets and all those that support javascript.
  • Can you think of any other?


Official API Docs for developers

What’s next

  • [x] Implement a demo app using this library. this is Asist, it can autenticate, sync, fetch and complete tasks from Todoist.
  • [ ] Implement a web oAuth2 process and document it.
  • [ ] Test browsers compatibility.
  • [ ] Test compatibility with Node.

Development / Testing

Clone this repo git clone [email protected]:Cosmitar/todoist-js.git.

This repo includes a Jest suite of tests, used for TDD. Before start, make sure you create a .env file (you can use .env-example as template) and complete, as minimum requirement, the variable ACCESS_TOKEN with a valid user access token (how to get an access token?). Then, install all dev dependencies by running npm install

❌ Do not run all tests together with npm run test or you’ll get a max request limit per seconds error.

Run each suite independently like:

npm run test -t api.spec.js

npm run test -t completed.spec.js

npm run test -t filter.spec.js and so on.

❗ Some tests can fail due to restrictions in your account if you’re not premium.

If you want to test share.spec.js you need first to include a 2nd access token (from a different user) into .env file, using variable ALTERNATIVE_ACCOUNT_ACCESS_TOKEN


Pull requests and issues are welcome. If you’ve found an bug, please open an issue.



Related Repositories



An implementation of the Todoist API for Node.js ...



The (un)official Todoist javascript API library ...