# Todoist

Todoist is a task management and productivity platform for organizing tasks, projects, and team collaboration. The Sling Todoist connector extracts data from the Todoist API v1, supporting projects, sections, tasks, labels, comments, and collaborators.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials are accepted:

**Secrets:**

* `api_token` **(required)** -> Your Todoist API Token

### Getting Your API Token

1. Log in to [Todoist](https://app.todoist.com)
2. Click your avatar (top-left corner)
3. Go to **Settings**
4. Navigate to **Integrations** in the left sidebar
5. Click **Developer**
6. Copy your **API token**

{% hint style="warning" %}
**Important:** API tokens grant the same access as your user account. Keep them secure and do not share them.
{% endhint %}

### Using `sling conns`

Here are examples of setting a connection named `TODOIST`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set TODOIST type=api spec=todoist secrets='{ api_token: your_api_token_here }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export TODOIST='{ type: api, spec: todoist, secrets: { api_token: "your_api_token_here" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  TODOIST:
    type: api
    spec: todoist
    secrets:
      api_token: "your_api_token_here"
```

## Replication

Here's an example replication configuration to sync Todoist data to a PostgreSQL database:

```yaml
source: TODOIST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: todoist.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Sync specific endpoints:**

```yaml
source: TODOIST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: todoist.{stream_name}

streams:
  projects:
  sections:
  tasks:
  labels:
  comments:
  collaborators:
```

## Endpoints

| Endpoint        | Description                                       | Incremental | Depends On |
| --------------- | ------------------------------------------------- | ----------- | ---------- |
| `projects`      | All projects accessible to the authenticated user | No          | —          |
| `sections`      | All sections across all projects                  | No          | —          |
| `tasks`         | All active tasks                                  | No          | —          |
| `labels`        | All personal labels                               | No          | —          |
| `comments`      | Comments for each task                            | No          | `tasks`    |
| `collaborators` | Collaborators for each project                    | No          | `projects` |

The connector uses a **queue-based architecture** to handle Todoist's hierarchical structure. The `projects` endpoint populates project IDs used by `collaborators`. The `tasks` endpoint populates task IDs used by `comments`.

To discover available endpoints:

```bash
sling conns discover TODOIST
```

### Endpoint Details

**`projects`** — Returns all projects the authenticated user has access to, including inbox project, shared projects, and their settings (color, view style, access permissions).

**`sections`** — Returns all sections across all projects, including section names, ordering, and archive status.

**`tasks`** — Returns all active (non-completed) tasks with full detail: content, description, priority, due dates, labels, parent task, project, and section assignment.

**`labels`** — Returns all personal labels created by the user, including label names, colors, and ordering.

**`comments`** — Returns all comments for each task. Iterates over task IDs collected from the `tasks` endpoint. Includes comment content, author, timestamps, and file attachments.

**`collaborators`** — Returns all collaborators for each project. Iterates over project IDs collected from the `projects` endpoint. Includes collaborator names and email addresses.

## Rate Limiting

The Todoist API enforces rate limits:

* **Standard limit:** 1000 requests per 15 minutes

The connector automatically:

* Uses conservative rate limiting (1 request/second with concurrency of 3)
* Retries with exponential backoff on 429 (rate limit) responses, up to 5 attempts
* Retries with exponential backoff on 5xx server errors, up to 3 attempts

## Common Use Cases

### Sync All Todoist Data

```yaml
source: TODOIST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: todoist.{stream_name}

streams:
  '*':
```

### Sync Tasks and Comments Only

```yaml
source: TODOIST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: todoist.{stream_name}

streams:
  tasks:
  comments:
```

### Export Projects and Collaborators

```yaml
source: TODOIST
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: todoist.{stream_name}

streams:
  projects:
  collaborators:
```

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/todoist.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.