---
name: todoist
description: Manage tasks and projects in Todoist via REST API v1. Use when user asks about tasks, to-dos, reminders, or productivity.
homepage: https://todoist.com
metadata:
  clawdbot:
    emoji: "✅"
---

# Todoist REST API v1

Uses the Todoist REST API v1 with Bearer token from `~/.todoist_token`.

## Setup

Token stored in `~/.todoist_token`. Read dynamically before each call.

## Core Commands

### List Tasks

```bash
TOKEN=$(cat ~/.todoist_token)
curl -s "https://api.todoist.com/api/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" | python3 -c "
import sys, json
tasks = json.load(sys.stdin).get('results', [])
for t in tasks:
    due = t.get('due', {}).get('date', '—')
    pri = t.get('priority', 1)
    check = '✅' if t.get('checked') else '⬜'
    print(f'{check} [{pri}] {t[\"content\"]} (fällig: {due})')
"
```

### Overdue / Filtered Tasks

Use the script: `/home/agent/.openclaw/workspace/scripts/todoist_overdue.sh`

Returns:
- HEUTE (due today)
- MORGEN (due tomorrow)  
- SPÄTER (due later)
- OHNE FÄLLIGKEITSDATUM (no due date)

### Add Task

```bash
TOKEN=$(cat ~/.todoist_token)
curl -s -X POST "https://api.todoist.com/api/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Task title",
    "due_date": "2026-05-10",
    "priority": 1
  }'
```

### Complete Task

```bash
TOKEN=$(cat ~/.todoist_token)
curl -s -X POST "https://api.todoist.com/api/v1/tasks/<id>/close" \
  -H "Authorization: Bearer $TOKEN"
```

### Update Task (due date, priority, etc.)

```bash
TOKEN=$(cat ~/.todoist_token)
curl -s -X PUT "https://api.todoist.com/api/v1/tasks/<id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"due_date": "2026-06-01", "priority": 2}'
```

### Delete Task

```bash
TOKEN=$(cat ~/.todoist_token)
curl -s -X DELETE "https://api.todoist.com/api/v1/tasks/<id>" \
  -H "Authorization: Bearer $TOKEN"
```

### Sync (get full state)

```bash
TOKEN=$(cat ~/.todoist_token)
curl -s -X POST "https://api.todoist.com/api/v1/sync" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 0}'
```

Returns `sync_token` for incremental syncs.

## Usage Examples

User: "Was steht an?"
→ Run `~/scripts/todoist_overdue.sh`

User: "Füge 'Arzttermin buchen' hinzu, fällig nächsten Montag"
→ POST with `due_date` calculated

User: "Markiere 'Backup Friday' als erledigt"
→ POST `/api/v1/tasks/<id>/close`

User: "Verschiebe 'Medgate' auf nächste Woche"
→ PUT `/api/v1/tasks/<id>` with new due_date

## Notes

- API v1 uses `content` field for task titles (not `name`)
- Task IDs are numeric strings (e.g., "42055733")
- Due dates in YYYY-MM-DD format
- Priority: 1 (highest) to 4 (lowest)
- `checked` boolean indicates completion status
- The `todoist_overdue.sh` script handles date classification automatically