Todoist

---
name: todoist
description: |
  Todoist API integration with managed OAuth. Manage tasks, projects, sections, labels, and comments. Use this skill when users want to create, update, complete, or organize tasks and projects in Todoist. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - MATON_API_KEY
---

# Todoist

Access the Todoist API v1 with managed OAuth authentication. Manage tasks, projects, sections, labels, and comments.

## Quick Start

```bash
# List all tasks
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/todoist/api/v1/tasks')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/todoist/api/v1/{resource}
```

The gateway proxies requests to `api.todoist.com/api/v1` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Todoist OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=todoist&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'todoist'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

**Response:**
```json
{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "todoist",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Specifying Connection

If you have multiple Todoist connections, specify which one to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/todoist/api/v1/tasks')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

### Projects

#### List Projects

```bash
GET /todoist/api/v1/projects
```

**Response:**
```json
{
  "results": [
    {
      "id": "6fwFRqmVCFvWVX5R",
      "name": "Inbox",
      "color": "charcoal",
      "parent_id": null,
      "child_order": 0,
      "is_shared": false,
      "is_favorite": false,
      "inbox_project": true,
      "view_style": "list",
      "description": "",
      "is_archived": false
    }
  ],
  "next_cursor": null
}
```

#### Get Project

```bash
GET /todoist/api/v1/projects/{id}
```

#### Create Project

```bash
POST /todoist/api/v1/projects
Content-Type: application/json

{
  "name": "My Project",
  "color": "blue",
  "is_favorite": true,
  "view_style": "board"
}
```

**Parameters:**
- `name` (required) - Project name
- `parent_id` - Parent project ID for nesting
- `color` - Project color (e.g., "red", "blue", "green")
- `is_favorite` - Boolean favorite status
- `view_style` - "list" or "board" (default: list)

**Example:**
```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'name': 'My New Project', 'color': 'blue'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/todoist/api/v1/projects', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

#### Update Project

```bash
POST /todoist/api/v1/projects/{id}
Content-Type: application/json

{
  "name": "Updated Project Name",
  "color": "red"
}
```

#### Delete Project

```bash
DELETE /todoist/api/v1/projects/{id}
```

Returns 204 No Content on success.

#### Get Project Collaborators

```bash
GET /todoist/api/v1/projects/{id}/collaborators
```

### Tasks

#### List Tasks

```bash
GET /todoist/api/v1/tasks
```

**Query Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `project_id` | string | Filter by project |
| `section_id` | string | Filter by section |
| `label` | string | Filter by label name |
| `filter` | string | Todoist filter expression |
| `ids` | string | Comma-separated task IDs |

**Response:**
```json
{
  "results": [
    {
      "id": "6fwhG9wMHr4wxgpR",
      "content": "Buy groceries",
      "description": "",
      "project_id": "6fwFRqmVCFvWVX5R",
      "section_id": null,
      "parent_id": null,
      "child_order": 1,
      "priority": 2,
      "checked": false,
      "labels": [],
      "due": {
        "date": "2026-02-07T10:00:00",
        "string": "tomorrow at 10am",
        "lang": "en",
        "is_recurring": false
      },
      "added_at": "2026-02-06T20:41:08.449320Z"
    }
  ],
  "next_cursor": null
}
```

#### Get Task

```bash
GET /todoist/api/v1/tasks/{id}
```

#### Create Task

```bash
POST /todoist/api/v1/tasks
Content-Type: application/json

{
  "content": "Buy groceries",
  "project_id": "2366834771",
  "priority": 2,
  "due_string": "tomorrow at 10am",
  "labels": ["shopping", "errands"]
}
```

**Required Fields:**
- `content` - Task content/title

**Optional Fields:**
- `description` - Task description
- `project_id` - Project to add task to (defaults to Inbox)
- `section_id` - Section within project
- `parent_id` - Parent task ID for subtasks
- `labels` - Array of label names
- `priority` - 1 (normal) to 4 (urgent)
- `due_string` - Natural language due date ("tomorrow", "next Monday 3pm")
- `due_date` - ISO format YYYY-MM-DD
- `due_datetime` - RFC3339 format with timezone
- `assignee_id` - User ID to assign task
- `duration` - Task duration (integer)
- `duration_unit` - "minute" or "day"

**Example:**
```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'content': 'Complete project report',
    'priority': 4,
    'due_string': 'tomorrow at 5pm',
    'labels': ['work', 'urgent']
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/todoist/api/v1/tasks', data=data, method='POST')
req.add_header('Authorization',