todoist-apiTodoist API integration with managed OAuth. Manage tasks, projects, sections, labels, and comments. Use this skill when users want to create, update, complet...
Install via ClawdBot CLI:
clawdbot install byungkyu/todoist-apiAccess the Todoist API v1 with managed OAuth authentication. Manage tasks, projects, sections, labels, and comments.
# 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))
EOFhttps://gateway.maton.ai/todoist/api/v1/{resource}The gateway proxies requests to api.todoist.com/api/v1 and automatically injects your OAuth token.
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEYEnvironment Variable: Set your API key as MATON_API_KEY:
export MATON_API_KEY="YOUR_API_KEY"Manage your Todoist OAuth connections at https://ctrl.maton.ai.
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))
EOFpython <<'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))
EOFpython <<'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))
EOFResponse:
{
"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.
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))
EOFIf you have multiple Todoist connections, specify which one to use with the Maton-Connection header:
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))
EOFIf omitted, the gateway uses the default (oldest) active connection.
GET /todoist/api/v1/projectsResponse:
{
"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 /todoist/api/v1/projects/{id}POST /todoist/api/v1/projects
Content-Type: application/json
{
"name": "My Project",
"color": "blue",
"is_favorite": true,
"view_style": "board"
}Parameters:
name (required) - Project nameparent_id - Parent project ID for nestingcolor - Project color (e.g., "red", "blue", "green")is_favorite - Boolean favorite statusview_style - "list" or "board" (default: list)Example:
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))
EOFPOST /todoist/api/v1/projects/{id}
Content-Type: application/json
{
"name": "Updated Project Name",
"color": "red"
}DELETE /todoist/api/v1/projects/{id}Returns 204 No Content on success.
GET /todoist/api/v1/projects/{id}/collaboratorsGET /todoist/api/v1/tasksQuery 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:
{
"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 /todoist/api/v1/tasks/{id}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/titleOptional Fields:
description - Task descriptionproject_id - Project to add task to (defaults to Inbox)section_id - Section within projectparent_id - Parent task ID for subtaskslabels - Array of label namespriority - 1 (normal) to 4 (urgent)due_string - Natural language due date ("tomorrow", "next Monday 3pm")due_date - ISO format YYYY-MM-DDdue_datetime - RFC3339 format with timezoneassignee_id - User ID to assign taskduration - Task duration (integer)duration_unit - "minute" or "day"Example:
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', 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))
EOFPOST /todoist/api/v1/tasks/{id}
Content-Type: application/json
{
"content": "Updated task content",
"priority": 3
}POST /todoist/api/v1/tasks/{id}/closeReturns 204 No Content. For recurring tasks, this schedules the next occurrence.
POST /todoist/api/v1/tasks/{id}/reopenReturns 204 No Content.
DELETE /todoist/api/v1/tasks/{id}Returns 204 No Content.
GET /todoist/api/v1/sections
GET /todoist/api/v1/sections?project_id={project_id}Response:
{
"results": [
{
"id": "6g424m6CQm47v7mm",
"project_id": "6g424jv8X52hP7qF",
"section_order": 1,
"name": "To Do",
"added_at": "2026-02-20T22:25:04.203675Z",
"is_archived": false,
"is_collapsed": false
}
],
"next_cursor": null
}GET /todoist/api/v1/sections/{id}POST /todoist/api/v1/sections
Content-Type: application/json
{
"name": "In Progress",
"project_id": "2366834771",
"order": 2
}Required Fields:
name - Section nameproject_id - Parent project IDPOST /todoist/api/v1/sections/{id}
Content-Type: application/json
{
"name": "Updated Section Name"
}DELETE /todoist/api/v1/sections/{id}Returns 204 No Content.
GET /todoist/api/v1/labelsResponse:
{
"results": [
{
"id": "2182980313",
"name": "urgent",
"color": "red",
"order": 1,
"is_favorite": false
}
],
"next_cursor": null
}GET /todoist/api/v1/labels/{id}POST /todoist/api/v1/labels
Content-Type: application/json
{
"name": "work",
"color": "blue",
"is_favorite": true
}Parameters:
name (required) - Label namecolor - Label colororder - Sort orderis_favorite - Boolean favorite statusPOST /todoist/api/v1/labels/{id}
Content-Type: application/json
{
"name": "updated-label",
"color": "green"
}DELETE /todoist/api/v1/labels/{id}Returns 204 No Content.
GET /todoist/api/v1/comments?task_id={task_id}
GET /todoist/api/v1/comments?project_id={project_id}Note: Either task_id or project_id is required.
Response:
{
"results": [
{
"id": "6g424pWVXPpwW7hR",
"item_id": "6g424pQr2xfCcFr2",
"content": "This is a comment",
"posted_at": "2026-02-20T22:25:20.045703Z",
"posted_uid": "57402826",
"file_attachment": null,
"reactions": null
}
],
"next_cursor": null
}GET /todoist/api/v1/comments/{id}POST /todoist/api/v1/comments
Content-Type: application/json
{
"task_id": "9993408170",
"content": "Don't forget to check the budget"
}Required Fields:
content - Comment texttask_id OR project_id - Where to attach the commentPOST /todoist/api/v1/comments/{id}
Content-Type: application/json
{
"content": "Updated comment text"
}DELETE /todoist/api/v1/comments/{id}Returns 204 No Content.
| Priority | Meaning |
|----------|---------|
| 1 | Normal (default) |
| 2 | Medium |
| 3 | High |
| 4 | Urgent |
Use ONE of these formats per request:
due_string - Natural language: "tomorrow", "next Monday at 3pm", "every week"due_date - Date only: "2026-02-15"due_datetime - Full datetime: "2026-02-15T14:00:00Z"// Create a task
const response = await fetch('https://gateway.maton.ai/todoist/api/v1/tasks', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
content: 'Review pull request',
priority: 3,
due_string: 'today at 5pm'
})
});
const task = await response.json();import os
import requests
# Create a task
response = requests.post(
'https://gateway.maton.ai/todoist/api/v1/tasks',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
json={
'content': 'Review pull request',
'priority': 3,
'due_string': 'today at 5pm'
}
)
task = response.json()jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments| Status | Meaning |
|--------|---------|
| 204 | Success (no content) - for close, reopen, delete operations |
| 400 | Invalid request or missing Todoist connection |
| 401 | Invalid or missing Maton API key |
| 404 | Resource not found |
| 429 | Rate limited |
| 4xx/5xx | Passthrough error from Todoist API |
MATON_API_KEY environment variable is set:echo $MATON_API_KEYpython <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFtodoist. For example:https://gateway.maton.ai/todoist/api/v1/taskshttps://gateway.maton.ai/api/v1/tasksGenerated Mar 1, 2026
Individuals can automate daily task creation, updates, and completion in Todoist via scripts or AI agents. This reduces manual entry, ensures consistency, and integrates with other personal productivity tools for streamlined workflows.
Teams in small businesses or startups use this skill to manage shared projects, assign tasks, and track progress programmatically. It facilitates collaboration by syncing task updates across members and automating reminders based on project deadlines.
Content creators and marketers organize editorial calendars, track content deadlines, and manage production stages in Todoist. This skill automates task creation for each content piece, from ideation to publication, improving workflow efficiency.
Freelancers manage multiple client projects by creating tasks, setting priorities, and logging time spent. This skill helps automate project setup, monitor milestones, and generate reports for billing and client updates.
Educators and students organize coursework, assignments, and study schedules in Todoist. This skill enables automated task creation for lesson plans, due dates, and group projects, enhancing academic organization and time management.
Companies offer this skill as part of a larger SaaS platform that integrates Todoist with other apps like CRM or calendar tools. Revenue comes from subscription fees for enhanced automation features and premium support.
Consultants use this skill to build custom Todoist automation solutions for clients, such as task management systems or workflow integrations. Revenue is generated through project-based fees and ongoing maintenance contracts.
Developers create a freemium productivity tool that leverages this skill for basic Todoist automation, with advanced features like AI-driven task prioritization available in paid tiers. Revenue streams include premium upgrades and in-app purchases.
💬 Integration Tip
Ensure the MATON_API_KEY is securely stored in environment variables and test connection management endpoints before integrating core API calls to avoid authentication issues.
Manage Trello boards, lists, and cards via the Trello REST API.
Sync and query CalDAV calendars (iCloud, Google, Fastmail, Nextcloud, etc.) using vdirsyncer + khal. Works on Linux.
Manage tasks and projects in Todoist. Use when user asks about tasks, to-dos, reminders, or productivity.
Master OpenClaw's timing systems. Use for scheduling reliable reminders, setting up periodic maintenance (janitor jobs), and understanding when to use Cron v...
Calendar management and scheduling. Create events, manage meetings, and sync across calendar providers.
Kanban-style task management dashboard for AI assistants. Manage tasks via CLI or dashboard UI. Use when user mentions tasks, kanban, task board, mission con...