CoIsland
Download
esc
↑↓ move↵ openesc close
Connectors · Issues & docs

Connect Todoist

Set up with your AI

Know what is due before it is late.

You need
API token Settings › Integrations › Developer app.todoist.com
The form asks
  • Connector name
  • API token
You can watch
  • Due and overdue
  • Filter
  • New tasks in a project
Access
GET requests only; it never completes or edits a task
On this page

To connect Todoist to CoIsland you need one thing: the API token of your own Todoist account. No admin, no app to register, no OAuth. CoIsland calls Todoist’s API v1 straight from your Mac, keeps the token in your login Keychain, and only ever reads. This page covers the token, the connector form, the three Todoist monitor kinds with queries you can paste, and the errors you may meet.

Copy your Todoist API token

  1. Open Todoist on the web or in the app.
  2. Go to Settings › Integrations › Developer (https://app.todoist.com/app/settings/integrations/developer).
  3. Select Copy API token.

Every Todoist account has one, on every plan. It acts as you and can read and change everything you can: CoIsland only ever sends reads. Resetting the token in the same place ends the old one.

Connect Todoist in CoIsland

Open Settings › Connectors, click +, and choose Todoist.

Field What to enter
Connector name What monitors call it: todoist. Letters, digits, _ and -.
API token The token you copied.

Test connector saves nothing. It calls GET /api/v1/user and shows your name, email and plan. When your Todoist time zone differs from your Mac’s, it says so: a due time without a zone is read in your Mac’s time zone.

Click Add Connector. The name goes to ~/Library/Application Support/CoIsland/connectors.json, the token to your login Keychain. The token is only ever sent to https://api.todoist.com, in the Authorization header.

Choose what to watch: the three Todoist monitor kinds

Open Monitors, add a monitor and choose Todoist. A new monitor’s first check records what is already there and raises nothing.

Due and overdue

Your tasks overdue, or due within the window: within:0d is today, 1d today and tomorrow, up to 14d. Narrow it with project: (picked by name, saved as an ID), label: and priority:p1,p2. A task alerts once per due day, so a recurring task alerts again on its next one.

within:0d priority:p1

Filter

Any Todoist filter, as in Todoist’s Filters view. Join filters with |: Todoist’s API takes one filter, not several separated by commas.

today | overdue
assigned to: me
#Work & p1

New tasks in a project

A task added to one project, by you or a collaborator. Optionally label:.

project:6Jf8VQXxpwv56VQ7

Click Test to run the query once: nothing is saved or alerted. A check reads up to 2,000 tasks.

What a Todoist alert shows

The notch lists each task as Work · Overdue, Tue 22 Sep · P1 · @finance: project, when it is due, priority and first label. Clicking it opens the alert in CoIsland, where the task fills in live: its description, labels, deadline, how it repeats, and its comments with their authors. Open in Todoist goes to the task.

What a Todoist monitor’s watch file looks like

-- name: Today and overdue
-- kind: todoist.due
-- connector: todoist
-- every: 5m
-- alert: new-rows

within:0d

The kinds are todoist.filter, todoist.due and todoist.project. Watch files lists every header key.

Rate limits

Todoist allows about 1,000 requests per 15 minutes per user. A check costs one request per 200 tasks, plus one for the projects’ names. The examples check every five minutes. When Todoist asks CoIsland to slow down, checks back off on their own.

Troubleshooting Todoist connector errors

  • The token was refused. Todoist answered 401: the token was mistyped, or it was reset in Settings › Integrations › Developer. Copy it again and update the connector.
  • Todoist refused the request: Invalid argument value (query). Todoist could not read the filter. Try it in Todoist’s own Filters view first.
  • One filter at a time. Replace the comma with |.
  • This task is no longer active in Todoist: completed or deleted. The alert keeps the task as it was.
  • Rate limited; retry after 22 s. The next check tries again.

Common questions

Does CoIsland need a Todoist admin?

No. The API token is your own, on every plan, Business included.

Can CoIsland complete a task?

No. It only reads. Complete it in Todoist, from Open in Todoist.

Next: Getting started for the rest of the app, or the Todoist connector for everything it can watch.

Stuck? Open an issue on GitHub, or write to hello@coisland.app.

Docs