How to use Hopper to manage your Todoist tasks from your watch

Todoist is one of the most popular task management apps, and with Hopper AI on your Wear OS watch, you can manage your Todoist tasks directly from your wrist using simple voice commands - no phone required.

Why Connect Hopper to Todoist?

Imagine completing a task while you're out and about and immediately marking it done with a quick voice command: "Mark buy groceries as complete." Or checking what's due today without pulling out your phone: "What tasks are due today?"

With Hopper and the Todoist API, your watch becomes a hands-free task manager.

This guide walks you through two setups:

1. Mark tasks as complete — close out tasks by name from your wrist.
2. Retrieve tasks by filters — find tasks by keywords, due date, and more.

Prerequisites

Before you begin, you'll need a Todoist API token:

1. Log in to your Todoist via the web app at https://todoist.com.
2. Click your avatar at the top-left.
3. Select Settings.
4. Select the Integrations tab.
5. Click the Developer tab at the top.
6. Click Copy API token. It's saved to your clipboard.

Or follow the steps in this Todoist blog for the most up-to-date tutorial on how to find your Todoist API token.

Setup 1: Mark a Task as Complete

This setup uses two tools that work together. When you say something like "Mark buy groceries as complete," Hopper's AI agent will first search for the task, then close it.

Tool 1: Search for a Task

This tool finds the task ID by searching your active tasks.

1. Open the Hopper companion phone app.
2. Tap the Tools icon in the bottom navbar and then Add Tool in the top right.
3. Fill in the following fields:

Field	Value
Name	get_tasks
URL	https://api.todoist.com/api/v1/tasks
Method	From the dropdown, select GET
Description	Retrieve a list of the user's active Todoist tasks. All parameters are optional and can be combined to narrow results. Use this when the user wants to see tasks from a specific project, section, parent task, or label, or when looking up specific tasks by ID. Returns a paginated list — use cursor to fetch subsequent pages.
Authentication	From the dropdown, select Bearer Token
Token/Value	Paste the API Token you obtained from your Todoist via the web app.

4. Add the following parameters:

Parameter	Type	Description
label	From the dropdown, select String	Use it to filter tasks by a label name (e.g. “work”, “urgent”). Returns only tasks that have this label assigned.
ids	From the dropdown, select String	A comma-separated list of specific task IDs to retrieve (e.g. “id1, id2, id3”). Use it when you already know the exact tasks you want.

5. Click Save to save the get_tasks tool.

Tool 2: Close a Task

This tool marks a task as complete using the task ID returned by the get_tasks tool.

1. Add another tool in the Tools tab in the Hopper companion app by clicking on Add Tool in the top right:

Field	Value
Name	close_task
URL	https://api.todoist.com/api/v1/tasks/{task_id}/close
Description for task_id	The string ID of the task to close. Obtain this from the ids field in the get_tasks tool’s response.
Method	From the dropdown, select POST
Description	Use it to mark a Todoist task as complete. Requires a task_id — call get_tasks first if you don't already have it. For regular tasks, this moves the task and its subtasks to history. For recurring tasks, this schedules the task to its next occurrence.
Authentication	From the dropdown, select Bearer Token
Token/Value	Paste the API Token you obtained from your Todoist via the web app.

2. Click Save to save the close_task tool.

How It Works

When you tell Hopper to complete a task, the AI agent uses the two tools together automatically:

1. It uses the search tool to find matching tasks based on your voice command.
2. It uses the close tool to mark it complete.
3. You get a confirmation on your watch of the task it marked complete.

Example voice commands:

• "Mark buy groceries as complete", if "buy groceries" is a task in Todoist.
• "Complete the dentist appointment task", if "dentist appointment" is a task in Todoist.
• "I finished the weekly report, mark it done", if "weekly report" is a task in Todoist.

Setup 2: Create a New Task

This setup lets you add a new Todoist task. You can include things like due dates, project, labels, priority, deadline, and description.

When you say something like "Add buy groceries tomorrow with label errands under project personal and priority p2", Hopper will create a task called "Buy Groceries" due tomorrow, filed under your "Personal" project, tagged with the "Errands" label, and set to priority 2.

Tool: Quick Add Tasks

1. Add another tool in the Tools tab in the Hopper companion app by clicking on Add Tool in the top right:

Field	Value
Name	quick_add_tasks
URL	https://api.todoist.com/api/v1/tasks/quick
Method	From the dropdown, select POST
Description	Use it to add a new task to Todoist using natural language. It parses a single text string to extract task details including due date, project, labels, assignee, priority, deadline, and description — all inline. Use this when the user wants to create a task, optionally with a reminder.
Authentication	From the dropdown, select Bearer Token
Token/Value	Paste the API Token you obtained from your Todoist via the web app.

2. Add the following parameters:

Parameter	Type	Description
text	From the dropdown, select String	The user’s task as a natural language string. You can embed metadata inline: due date in free form (e.g. "tomorrow at 3pm"), project with # (e.g. #Work), label with @ (e.g. @urgent), assignee with + (e.g. +john), priority with p1–p4, deadline in {} (e.g. {in 3 days}), and description after // (e.g. // Add notes here). Example: if the user says “Add buy groceries tomorrow with label errands under project personal and priority p2” the text parameter should be"Buy groceries tomorrow @errands #Personal p2".
note	From the dropdown, select String	An optional note to attach to the todoist task.
reminder (add only if on Pro plan)	From the dropdown, select String	An optional reminder time in free form text (e.g. "30 minutes before", "tomorrow at 9am").

3. Click Save to save the quick_add_tasks tool.

Setup 3: Retrieve Tasks by Filters

This setup lets you get your Todoist tasks filtered by various parameters like keyword, due date, priority, deadline, created at date and sub-tasks.

Tool: Get Filtered Tasks

1. Add another tool in the Tools tab in the Hopper companion app by clicking on Add Tool in the top right:

Field	Value
Name	get_tasks_by_query
URL	https://api.todoist.com/api/v1/tasks/filter
Method	From the dropdown, select POST

2. In the Description field, paste the following (click here to copy):

Use this tool to get a user's Todoist tasks based on a query. Use the parameters below to filter the tasks based on the user's query.

## Filter Parameters

### 1. Keyword Search
If a user asks to filter tasks by a keyword or phrase present in the task name, use `search:` followed by the keyword (use `keyword*` as wildcard).

### 2. Due Date
If a user asks to filter tasks based on their due date, use `date:`, `date before:`, `date after:`, or `no date`.

- **Specific date:** Use `date:` followed by the date/phrase.
  - Examples: `"date:Jan 3"`, `"date:today"`, `"date:next week"`
- **Before a date:** Use `date before:` — e.g. `"date before:Dec 25"`
- **After a date:** Use `date after:` — e.g. `"date after:Jan 1"`
- **No due date:** Use `"no date"`

### 3. Priority
If a user wants to filter tasks based on priority, use the priority level as the parameter: `p1` (highest) to `p4` (lowest).

### 4. Deadline / Recurrence
If a user asks to filter by deadline rule or recurrence, use `deadline:`, `no deadline`, or `recurring`.

- **Due today:** Use `"deadline:today"`
- **Specific deadline date:** Use `"deadline:Dec 31"`
- **No deadline:** Use `"no deadline"` (non-recurring tasks with no specific deadline)
- **All recurring tasks:** Use `"recurring"`

### 5. Creation Date
If a user asks to filter tasks based on when they were created, use `created:`, `created before:`, or `created after:`.

- **Specific date:** Use `created:` followed by the date/phrase.
  - Examples: `"created:today"`, `"created:last week"`
- **Before a date:** Use `"created before:Jan 1 2023"`
- **After a date:** Use `"created after:July 1 2023"`

### 6. Sub-task Status
If a user asks to filter by sub-task status:
- `subtask` — show only sub-tasks
- `!subtask` — show only parent tasks or standalone tasks

---

## Combining & Modifying Filters

### Logical Operators

| Operator | Meaning | Example |
|----------|---------|---------|
| `&` | AND — all conditions must be met | `"p1 & date:today"` |
| `\|` | OR — at least one condition must be met | `"@work \| @home"` |
| `!` | NOT — negate a filter | `"!date:today"`, `"!#Work"` |
| `()` | Group conditions for complex logic | `"p1 & (date:today \| date:tomorrow)"` |
| `,` | Separate queries into distinct sections | `"date:today, date:upcoming"` |

### Escaping Special Characters
To use a special character (`&`, `|`, `!`, `(`, `)`, `,`, `#`, `@`, `/`) as part of a name rather than a filter operator, escape it with a `\` (backslash).

- Project named "My #Project" → `"#My \#Project"`
- Section named "Q1 Budget" → `"/Q1\ Budget"`

3. Fill in the remaining fields:

Field	Value
Authentication	From the dropdown, select Bearer Token
Token/Value	Paste the API Token you obtained from your Todoist via the web app.

4. Add the following parameters:

Field	Value
Parameter name	query
Dropdown	From the dropdown, select String

In the Parameter Description, copy and paste the text below (click here to copy):

A Todoist filter string used to retrieve matching tasks. Supports filtering by keyword (search:), due date (date:, date before:, date after:, no date), priority (p1–p4), deadline (deadline:, no deadline, recurring), creation date (created:, created before:, created after:), and sub-task status (subtask, !subtask). Filters can be combined using & (AND), | (OR), ! (NOT), and () for grouping. Note: the , operator for multiple separate queries is not supported. Special characters used in names must be escaped with a backslash (e.g. \\#).

5. Click Save to save the get_tasks_by_query tool.

Example Voice Commands

• "What tasks are due today?"
• "Show me my high priority tasks"
• "What's on my to-do list for this week?"
• "Do I have any tasks with the keyword report?"

Best Practices

• Use Descriptive Tool Descriptions: Clear descriptions help Hopper's AI agent understand when to call each tool and how to chain them together.
• Test Your Setup: Try a simple task first to make sure everything is connected properly.
• Keep Your API Token Secure: Your Todoist API token gives full access to your account. Never share it publicly.

Add More Capabilities

You're not limited to the tools above. The Todoist API has endpoints for updating tasks, managing projects, labels, comments, and more. You can turn any API endpoint into a Hopper tool using ChatGPT (or your preferred LLM).

How It Works

1. Go to the Todoist API docs and find the endpoint you want (e.g. Update a Task).
2. Copy the prompt below into your LLM, replacing the placeholder with the API documentation for your chosen endpoint.
3. Paste the LLM's output into the Hopper companion app as a new tool.

Prompt Template

Copy the prompt below and paste it into ChatGPT or your preferred LLM (click here to copy):

Convert the following API endpoint into a Hopper tool configuration. Use the example below as a reference for the format.

## Example Hopper Tool

Tool fields:

| Field | Value |
|-------|-------|
| **Name** | `get_tasks` |
| **URL** | `https://api.todoist.com/api/v1/tasks` |
| **Method** | GET |
| **Description** | `Retrieve a list of the user's active Todoist tasks. All parameters are optional and can be combined to narrow results. Use this when the user wants to see tasks from a specific project, section, parent task, or label, or when looking up specific tasks by ID. Returns a paginated list — use cursor to fetch subsequent pages.` |
| **Authentication** | Bearer Token |

Parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `label` | String | `Use it to filter tasks by a label name (e.g. "work", "urgent"). Returns only tasks that have this label assigned.` |
| `ids` | String | `A comma-separated list of specific task IDs to retrieve (e.g. "id1, id2, id3"). Use it when you already know the exact tasks you want.` |

## Rules

- The **Description** field should explain what the tool does and when to use it, written for an AI agent that will decide when to call this tool.
- Each **Parameter Description** should explain what the parameter does and give examples. Write it for an AI agent.
- For URL path parameters (e.g. `{task_id}`), keep them in the URL with curly braces and add a **Description for [param_name]** row to the tool fields table explaining what it is and where to obtain it.
- Only include parameters that are useful for a voice-controlled assistant on a smartwatch. Skip parameters that are overly technical or rarely used.
- The **Type** should be one of: String, Number, Boolean, Object, Array.

## API Endpoint to Convert

[PASTE THE API ENDPOINT DOCUMENTATION HERE]

That's it — paste the LLM's output into the Hopper companion app, add your Todoist API token under Authentication, and you've got a new tool.

Start managing your tasks hands-free!