# Todoist

Create, update, complete and move tasks in Todoist, read completed tasks, and manage projects, sections, comments, labels and reminders.

## Connect Todoist

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `todoist` and choose **Todoist**.
3. Choose **Sign in with Todoist**.
4. Press **Sign in with Todoist** at the bottom of the sheet, then choose your account in Todoist’s window and allow access.

Or choose **Paste your API token**, paste it, and press **Test and save**. It stays until someone deletes it.

Sign in with Todoist, or paste your personal API token (Todoist → Settings → Integrations → Developer).

**What if it says “Sign-in isn’t set up here yet”?**

Signing in with Todoist needs a Todoist app on this installation, and it has none yet. Until it is set up, **Paste your API token** works without it.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Todoist sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Todoist’s developer settings ([Todoist’s guide](https://app.todoist.com/app/settings/integrations/developer)).
2. In GoRunner, copy the **Redirect address to add in Todoist’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Todoist app?**

Yes. In the sheet, open **Use your own Todoist app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Todoist**. The trigger uses the same connection as the steps.

### On New or Completed Task

Checks Todoist about once a minute and starts a run for each task added, or completed, since the check before, oldest first (at most 100 a minute; the rest follow). The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. New task reads the active tasks (at most 2,000; pick a project for a bigger list), so a task added and completed between two checks is not seen; a task moved in from another project does not count as new. A recurring task fires each time it is completed.

- **Trigger on · Required**: What starts a run. Options: New task, Task completed. Default: New task.
- **Project · Optional**: Only tasks in this project. Empty watches every project.

A later step can use its data, such as `{{trigger.added_at}}`, `{{trigger.change_type}}`, `{{trigger.completed_at}}` and 9 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Todoist

Add a **Todoist** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Task](https://docs.gorunner.io/apps/todoist#fields-f-task): Create · Quick Add · Get · Get Many · Get Completed · Update · Move · Close (complete) · Reopen · Delete
- [Project](https://docs.gorunner.io/apps/todoist#fields-f-project): Create · Get · Get Many · Update · Archive · Unarchive · Get Collaborators · Delete
- [Section](https://docs.gorunner.io/apps/todoist#fields-f-section): Create · Get · Get Many · Update · Archive · Unarchive · Delete
- [Comment](https://docs.gorunner.io/apps/todoist#fields-f-comment): Create · Get · Get Many · Update · Delete
- [Label](https://docs.gorunner.io/apps/todoist#fields-f-label): Create · Get · Get Many · Update · Delete · Get Many Shared · Rename Shared · Remove Shared
- [Reminder](https://docs.gorunner.io/apps/todoist#fields-f-reminder): Create · Get · Get Many · Update · Delete

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Todoist can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Todoist says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Todoist is `pieceId: "todoist"` with `actionId: "todoist"`, set by `resource` and an `operation_…` field, such as `operation_comment`. Its trigger is `todoisttrigger` / `todoist_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Todoist › Task

### Create

- **Content · Required**: The task's title. Markdown links and formatting work as in the app.
- **Description · Optional**: Notes under the task's title.
- **Project · Optional**: The project. Empty is the Inbox on Create, and every project on Get Many and Get Completed.
- **Section · Optional**: A section of the project.
- **Parent Task · Optional**: The id or link of the task this one sits under (a subtask).
- **Labels · Optional**: Label names (such as launch, waiting). Todoist creates a personal label that does not exist yet. On Update the list replaces the task's labels.
- **Priority · Optional**: 4 is the most urgent (shown as p1 in the app), 1 is normal (p4).
- **Due (in words) · Optional**: The due date as you would type it: tomorrow 5pm, every monday, Nov 7. On Update, "no date" removes it.
- **Due Date · Optional**: A due date without a time.
- **Due Date and Time · Optional**: A due date and time (ISO 8601). Give only one of the three due fields.
- **Due Language · Optional**: The language Due (in words) is written in: en, de, fr, es, … Empty is your Todoist language.
- **Deadline · Optional**: A deadline date, separate from the due date.
- **Duration · Optional**: How long the task takes, in Duration Unit. Needs a due date with a time when the unit is minutes.
- **Duration Unit · Optional**: Options: Minutes, Days. Default: Minutes.
- **Assignee · Optional**: The user id of a collaborator in a shared project (Project › Get Collaborators lists them).
- **Order · Optional**: The task's position among its siblings (1 is first).

### Quick Add

- **Text · Required**: The task as you would type it in Todoist's Quick Add, such as Send the launch note tomorrow 5pm #Work @launch p1.
- **Comment · Optional**: A comment to add to the new task.
- **Reminder · Optional**: When to be reminded, in words (such as tomorrow 9am).
- **Default Reminder · Optional**: Add your default reminder when the task has a due time. Off by default.

### Get, Close (complete), Reopen and Delete

- **Task · Required**: The task's id, or its link from the Todoist app.

### Get Many

- **Project · Optional**: The project. Empty is the Inbox on Create, and every project on Get Many and Get Completed.
- **Section · Optional**: A section of the project.
- **Parent Task · Optional**: The id or link of the task this one sits under (a subtask).
- **Label · Optional**: Only tasks with this label.
- **Task IDs · Optional**: Only these tasks: ids separated by commas.
- **Filter · Optional**: A Todoist filter, such as today | overdue, or #Work & p1. When set, it replaces Project, Section, Parent Task, Label and Task IDs. It is used as written: to narrow by a value from an earlier step, use those fields instead.
- **Filter Language · Optional**: The language the Filter is written in. Empty is English.
- **Return All · Optional**: Read every task, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many tasks to return (1–2000). Default: 50. Shows when **Return All** is off.

### Get Completed

- **Date Range Applies To · Optional**: Options: When the task was completed (up to 3 months), When the task was due (up to 6 weeks). Default: When the task was completed (up to 3 months).
- **From · Required**: The start of the range (ISO 8601 date and time).
- **To · Required**: The end of the range (ISO 8601 date and time).
- **Project · Optional**: The project. Empty is the Inbox on Create, and every project on Get Many and Get Completed.
- **Section · Optional**: A section of the project.
- **Parent Task · Optional**: The id or link of the task this one sits under (a subtask).
- **Filter · Optional**: A Todoist filter, such as today | overdue, or #Work & p1. When set, it replaces Project, Section, Parent Task, Label and Task IDs. It is used as written: to narrow by a value from an earlier step, use those fields instead.
- **Filter Language · Optional**: The language the Filter is written in. Empty is English.
- **Return All · Optional**: Read every task, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many tasks to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Task · Required**: The task's id, or its link from the Todoist app.
- **Content · Optional**: A new title for the task. Empty keeps it.
- **Description · Optional**: Notes under the task's title.
- **Labels · Optional**: Label names (such as launch, waiting). Todoist creates a personal label that does not exist yet. On Update the list replaces the task's labels.
- **Priority · Optional**: 4 is the most urgent (shown as p1 in the app), 1 is normal (p4).
- **Due (in words) · Optional**: The due date as you would type it: tomorrow 5pm, every monday, Nov 7. On Update, "no date" removes it.
- **Due Date · Optional**: A due date without a time.
- **Due Date and Time · Optional**: A due date and time (ISO 8601). Give only one of the three due fields.
- **Due Language · Optional**: The language Due (in words) is written in: en, de, fr, es, … Empty is your Todoist language.
- **Deadline · Optional**: A deadline date, separate from the due date.
- **Duration · Optional**: How long the task takes, in Duration Unit. Needs a due date with a time when the unit is minutes.
- **Duration Unit · Optional**: Options: Minutes, Days. Default: Minutes.
- **Assignee · Optional**: The user id of a collaborator in a shared project (Project › Get Collaborators lists them).
- **Order · Optional**: The task's position among its siblings (1 is first).

### Move

- **Task · Required**: The task's id, or its link from the Todoist app.
- **Project · Optional**: The project to move the task to. Give a Project, a Section or a Parent Task.
- **Section · Optional**: A section of the project.
- **Parent Task · Optional**: The id or link of the task this one sits under (a subtask).

### Todoist › Project

### Create

- **Name · Required**: The project's name.
- **Parent Project · Optional**: Create it inside this project.
- **Color · Optional**: Options: Berry red to Taupe (20 options).
- **Favorite · Optional**: Show it under Favorites in the sidebar.
- **View · Optional**: Options: List, Board, Calendar.

### Get, Archive, Unarchive and Delete

- **Project · Required**: The project.

### Get Many

- **Archived Projects · Optional**: List the archived projects instead of the active ones. Off by default.
- **Return All · Optional**: Read every item, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Project · Required**: The project.
- **Name · Optional**: A new name. Empty keeps it.
- **Color · Optional**: Options: Berry red to Taupe (20 options).
- **Favorite · Optional**: Show it under Favorites in the sidebar.
- **View · Optional**: Options: List, Board, Calendar.

### Get Collaborators

- **Project · Required**: The project.
- **Return All · Optional**: Read every item, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many items to return (1–2000). Default: 50. Shows when **Return All** is off.

### Todoist › Section

### Create

- **Project · Required**: The project to add the section to.
- **Name · Required**: The section's name.
- **Order · Optional**: The section's position in the project (1 is first).

### Get, Archive, Unarchive and Delete

- **Project · Optional**: Only the sections of this project. Empty is every project.
- **Section · Required**: The section.

### Get Many

- **Project · Optional**: Only the sections of this project. Empty is every project.
- **Return All · Optional**: Read every section, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many sections to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Project · Optional**: Only the sections of this project. Empty is every project.
- **Section · Required**: The section.
- **Name · Required**: The section's name.

### Todoist › Comment

### Create

- **Comment On · Optional**: Options: A task, A project. Default: A task.
- **Task · Required**: The task's id, or its link from the Todoist app. Shows when **Comment On** is **A task**.
- **Project · Required**: The project. Shows when **Comment On** is **A project**.
- **Comment · Required**: The comment's text (Markdown works as in the app; at most 15,000 characters).
- **Attachment URL · Optional**: A link to a file to attach to the comment.
- **Attachment Name · Optional**: The file's name as shown (such as agenda.pdf). Empty takes it from the URL.
- **Attachment Type · Optional**: The file's MIME type.
- **Notify · Optional**: User ids of collaborators to notify about the comment.

### Get and Delete

- **Comment · Required**: The comment's id.

### Get Many

- **Comment On · Optional**: Options: A task, A project. Default: A task.
- **Task · Required**: The task's id, or its link from the Todoist app. Shows when **Comment On** is **A task**.
- **Project · Required**: The project. Shows when **Comment On** is **A project**.
- **Return All · Optional**: Read every comment, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many comments to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Comment · Required**: The comment's id.
- **Comment · Required**: The comment's text (Markdown works as in the app; at most 15,000 characters).

### Todoist › Label

### Create

- **Name · Required**: The label's name (at most 128 characters).
- **Color · Optional**: Options: Berry red to Taupe (20 options).
- **Order · Optional**: The label's position in the list.
- **Favorite · Optional**: Show it under Favorites in the sidebar.

### Get and Delete

- **Label · Required**: The personal label.

### Get Many

- **Return All · Optional**: Read every label, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many labels to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Label · Required**: The personal label.
- **Name · Optional**: A new name; tasks with the label keep it under the new name. Empty keeps it.
- **Color · Optional**: Options: Berry red to Taupe (20 options).
- **Order · Optional**: The label's position in the list.
- **Favorite · Optional**: Show it under Favorites in the sidebar.

### Get Many Shared

- **Leave Out Personal Labels · Optional**: List only the labels used in shared projects, not your own labels of the same names. Off by default.
- **Return All · Optional**: Read every label, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many labels to return (1–2000). Default: 50. Shows when **Return All** is off.

### Rename Shared

- **Shared Label · Required**: The shared label's name.
- **New Name · Required**: The name to give it on every task.

### Remove Shared

- **Shared Label · Required**: The shared label's name.

### Todoist › Reminder

### Create

- **Task · Required**: The task to remind about: its id, or its link from the Todoist app.
- **Type · Optional**: On Update, the kind of time the new values set. Options: Before the task is due, At a date and time. Default: Before the task is due.
- **Minutes Before · Optional**: How many minutes before the task's due time to remind (the task needs a due time). 0 is at the due time. Shows when **Type** is **Before the task is due**.
- **Remind At · Optional**: The date and time (ISO 8601). Without a time zone it is in Time Zone, or your own. Shows when **Type** is **At a date and time**.
- **Remind At (in words) · Optional**: Or the moment in words, such as tomorrow at 9am. Give one of the two. Shows when **Type** is **At a date and time**.
- **Time Zone · Optional**: An IANA time zone for Remind At. Shows when **Type** is **At a date and time**.
- **Send By · Optional**: Empty uses your Todoist settings. Options: Push notification, Email.
- **Notify User · Optional**: The user id of the collaborator to remind. Empty reminds you.

### Get and Delete

- **Reminder · Required**: The reminder's id.

### Get Many

- **Task · Optional**: Only this task's reminders. Empty lists every reminder.
- **Return All · Optional**: Read every reminder, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many reminders to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Reminder · Required**: The reminder's id.
- **Type · Optional**: On Update, the kind of time the new values set. Options: Before the task is due, At a date and time. Default: Before the task is due.
- **Minutes Before · Optional**: How many minutes before the task's due time to remind (the task needs a due time). 0 is at the due time. Shows when **Type** is **Before the task is due**.
- **Remind At · Optional**: The date and time (ISO 8601). Without a time zone it is in Time Zone, or your own. Shows when **Type** is **At a date and time**.
- **Remind At (in words) · Optional**: Or the moment in words, such as tomorrow at 9am. Give one of the two. Shows when **Type** is **At a date and time**.
- **Time Zone · Optional**: An IANA time zone for Remind At. Shows when **Type** is **At a date and time**.
- **Send By · Optional**: Empty uses your Todoist settings. Options: Push notification, Email.
- **Notify User · Optional**: The user id of the collaborator to remind. Empty reminds you.

Source: https://docs.gorunner.io/apps/todoist