todoist-api

What this skill does

# Todoist API Integration Skill

Master the Todoist API for task management automation, including projects, tasks, labels, filters, webhooks, and Python SDK patterns. This skill covers REST API v2, Sync API v9, and integration patterns.

## When to Use This Skill

### USE Todoist API when:
- Automating task creation from external systems
- Building integrations with other productivity tools
- Creating custom task dashboards or reports
- Implementing GTD workflows programmatically
- Syncing tasks with calendar applications
- Building CLI tools for task management
- Automating recurring task patterns
- Integrating with CI/CD for project tracking

### DON'T USE Todoist API when:
- Need complex project management (use Jira, Asana)
- Require database-style queries (use Notion API)
- Need real-time collaboration on tasks (use Linear)
- Building for enterprise with SSO requirements
- Need Gantt charts or resource management

## Prerequisites

### API Authentication

```bash
# Get your API token from:
# https://todoist.com/app/settings/integrations/developer

# Set environment variable
export TODOIST_API_KEY="your-api-token-here"

# Verify authentication
curl -s -X GET "https://api.todoist.com/rest/v2/projects" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq '.[0]'
```

### Python SDK Installation

```bash
# Install official Python SDK
pip install todoist-api-python

# Or with uv
uv pip install todoist-api-python

# For sync API features
pip install todoist-api-python requests
```

### Verify Setup

```python
from todoist_api_python import TodoistAPI

api = TodoistAPI("your-api-token")

# Test connection
try:
    projects = api.get_projects()
    print(f"Connected! Found {len(projects)} projects")
except Exception as e:
    print(f"Connection failed: {e}")
```

## Core Capabilities

### 1. Projects Management

**REST API - Projects:**
```bash
# List all projects
curl -s -X GET "https://api.todoist.com/rest/v2/projects" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq

# Get specific project
curl -s -X GET "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq

# Create project
curl -s -X POST "https://api.todoist.com/rest/v2/projects" \
    -H "Authorization: Bearer $TODOIST_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Work Tasks",
        "color": "blue",
        "is_favorite": true,
        "view_style": "list"
    }' | jq

# Create sub-project
curl -s -X POST "https://api.todoist.com/rest/v2/projects" \
    -H "Authorization: Bearer $TODOIST_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Q1 Goals",
        "parent_id": "PARENT_PROJECT_ID",
        "color": "green"
    }' | jq

# Update project
curl -s -X POST "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Work Tasks - Updated",
        "color": "red"
    }' | jq

# Delete project
curl -s -X DELETE "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY"

# Get project collaborators
curl -s -X GET "https://api.todoist.com/rest/v2/projects/PROJECT_ID/collaborators" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq
```

**Python SDK - Projects:**
```python
from todoist_api_python import TodoistAPI
import os

api = TodoistAPI(os.environ["TODOIST_API_KEY"])

# List all projects
projects = api.get_projects()
for project in projects:
    print(f"{project.name} (ID: {project.id})")

# Get specific project
project = api.get_project(project_id="2345678901")
print(f"Project: {project.name}, Color: {project.color}")

# Create project
new_project = api.add_project(
    name="New Project",
    color="blue",
    is_favorite=True,
    view_style="board"  # "list" or "board"
)
print(f"Created: {new_project.name} (ID: {new_project.id})")

# Create sub-project
sub_project = api.add_project(
    name="Sub Project",
    parent_id="2345678901",
    color="green"
)

# Update project
updated = api.update_project(
    project_id="2345678901",
    name="Updated Name",
    color="red"
)

# Delete project
api.delete_project(project_id="2345678901")

# Get project sections
sections = api.get_sections(project_id="2345678901")
for section in sections:
    print(f"  Section: {section.name}")
```

### 2. Tasks Management

**REST API - Tasks:**
```bash
# List all tasks
curl -s -X GET "https://api.todoist.com/rest/v2/tasks" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq

# Get tasks with filter
curl -s -X GET "https://api.todoist.com/rest/v2/tasks?filter=today" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq

# Get tasks for specific project
curl -s -X GET "https://api.todoist.com/rest/v2/tasks?project_id=PROJECT_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq

# Get single task
curl -s -X GET "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY" | jq

# Create task with all options
curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
    -H "Authorization: Bearer $TODOIST_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "content": "Complete project report",
        "description": "Include Q4 metrics and projections",
        "project_id": "PROJECT_ID",
        "section_id": "SECTION_ID",
        "parent_id": null,
        "order": 1,
        "labels": ["work", "urgent"],
        "priority": 4,
        "due_string": "tomorrow at 5pm",
        "due_lang": "en",
        "assignee_id": null
    }' | jq

# Create task with natural language due date
curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
    -H "Authorization: Bearer $TODOIST_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "content": "Weekly review",
        "due_string": "every friday at 4pm"
    }' | jq

# Update task
curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "content": "Updated task content",
        "priority": 3,
        "due_string": "next monday"
    }' | jq

# Complete task
curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID/close" \
    -H "Authorization: Bearer $TODOIST_API_KEY"

# Reopen task
curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID/reopen" \
    -H "Authorization: Bearer $TODOIST_API_KEY"

# Delete task
curl -s -X DELETE "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
    -H "Authorization: Bearer $TODOIST_API_KEY"
```

**Python SDK - Tasks:**
```python
from todoist_api_python import TodoistAPI
from datetime import datetime, timedelta
import os

api = TodoistAPI(os.environ["TODOIST_API_KEY"])

# Get all tasks
tasks = api.get_tasks()
for task in tasks:
    due = task.due.string if task.due else "No due date"
    print(f"- [{task.priority}] {task.content} (Due: {due})")

# Get tasks with filter
today_tasks = api.get_tasks(filter="today")
overdue_tasks = api.get_tasks(filter="overdue")
high_priority = api.get_tasks(filter="p1 | p2")

# Get tasks for project
project_tasks = api.get_tasks(project_id="2345678901")

# Create task
new_task = api.add_task(
    content="Review pull requests",
    description="Check all open PRs in main repo",
    project_id="2345678901",
    section_id="3456789012",
    labels=["work", "development"],
    priority=4,  # 1=normal, 2=medium, 3=high, 4=urgent
    due_string="tomorrow at 10am",
    due_lang="en"
)
print(f"Created task: {new_task.id}")

# Create sub-task
sub_task = api.add_task(
    content="Review frontend PR #123",
    parent_id=new_task.id,
    priority=3
)

# Create recurring task
recurring_task = api.add_task(
    content="Weekly team standup",
    due_string="every monday at 9am"
)

# Update task
updated_task = api.update_task(
    task_id=new_task.id,
    content="Review all pull requests",
    priority=4,
    due_string="toda