Todoist

Todoist

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

Quick Start

# List all tasks
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/todoist/rest/v2/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/rest/v2/{resource}

The gateway proxies requests to api.todoist.com/rest/v2 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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

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

List Connections

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

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

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:

{
  "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

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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/todoist/rest/v2/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

GET /todoist/rest/v2/projects

Response:

[
  {
    "id": "2366738772",
    "name": "Inbox",
    "color": "charcoal",
    "parent_id": null,
    "order": 0,
    "is_shared": false,
    "is_favorite": false,
    "is_inbox_project": true,
    "view_style": "list",
    "url": "https://app.todoist.com/app/project/..."
  }
]

Get Project

GET /todoist/rest/v2/projects/{id}

Create Project

POST /todoist/rest/v2/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:

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/rest/v2/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

POST /todoist/rest/v2/projects/{id}
Content-Type: application/json

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

Delete Project

DELETE /todoist/rest/v2/projects/{id}

Returns 204 No Content on success.

Get Project Collaborators

GET /todoist/rest/v2/projects/{id}/collaborators

Tasks

List Tasks

GET /todoist/rest/v2/tasks

Query Parameters:

Response:

[
  {
    "id": "9993408170",
    "content": "Buy groceries",
    "description": "",
    "project_id": "2366834771",
    "section_id": null,
    "parent_id": null,
    "order": 1,
    "priority": 2,
    "is_completed": false,
    "labels": [],
    "due": {
      "date": "2026-02-07",
      "string": "tomorrow",
      "lang": "en",
      "is_recurring": false
    },
    "url": "https://app.todoist.com/app/task/9993408170",
    "comment_count": 0,
    "created_at": "2026-02-06T20:41:08.449320Z"
  }
]

Get Task

GET /todoist/rest/v2/tasks/{id}

Create Task

POST /todoist/rest/v2/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:

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/rest/v2/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))
EOF

Update Task

POST /todoist/rest/v2/tasks/{id}
Content-Type: application/json

{
  "content": "Updated task content",
  "priority": 3
}

Close Task (Complete)

POST /todoist/rest/v2/tasks/{id}/close

Returns 204 No Content. For recurring tasks, this schedules the next occurrence.

Reopen Task

POST /todoist/rest/v2/tasks/{id}/reopen

Returns 204 No Content.

Delete Task

DELETE /todoist/rest/v2/tasks/{id}

Returns 204 No Content.

Sections

List Sections

GET /todoist/rest/v2/sections
GET /todoist/rest/v2/sections?project_id={project_id}

Response:

[
  {
    "id": "214670251",
    "project_id": "2366834771",
    "order": 1,
    "name": "To Do"
  }
]

Get Section

GET /todoist/rest/v2/sections/{id}

Create Section

POST /todoist/rest/v2/sections
Content-Type: application/json

{
  "name": "In Progress",
  "project_id": "2366834771",
  "order": 2
}

Required Fields:

• name - Section name
• project_id - Parent project ID

Update Section

POST /todoist/rest/v2/sections/{id}
Content-Type: application/json

{
  "name": "Updated Section Name"
}

Delete Section

DELETE /todoist/rest/v2/sections/{id}

Returns 204 No Content.

Labels

List Labels

GET /todoist/rest/v2/labels

Response:

[
  {
    "id": "2182980313",
    "name": "urgent",
    "color": "red",
    "order": 1,
    "is_favorite": false
  }
]

Get Label

GET /todoist/rest/v2/labels/{id}

Create Label

POST /todoist/rest/v2/labels
Content-Type: application/json

{
  "name": "work",
  "color": "blue",
  "is_favorite": true
}

Parameters:

• name (required) - Label name
• color - Label color
• order - Sort order
• is_favorite - Boolean favorite status

Update Label

POST /todoist/rest/v2/labels/{id}
Content-Type: application/json

{
  "name": "updated-label",
  "color": "green"
}

Delete Label

DELETE /todoist/rest/v2/labels/{id}

Returns 204 No Content.

Comments

List Comments

GET /todoist/rest/v2/comments?task_id={task_id}
GET /todoist/rest/v2/comments?project_id={project_id}

Note: Either task_id or project_id is required.

Response:

[
  {
    "id": "3966541561",
    "task_id": "9993408170",
    "project_id": null,
    "content": "This is a comment",
    "posted_at": "2026-02-06T20:41:35.734376Z",
    "posted_by_id": "57402826"
  }
]

Get Comment

GET /todoist/rest/v2/comments/{id}

Create Comment

POST /todoist/rest/v2/comments
Content-Type: application/json

{
  "task_id": "9993408170",
  "content": "Don't forget to check the budget"
}

Required Fields:

• content - Comment text
• task_id OR project_id - Where to attach the comment

Update Comment

POST /todoist/rest/v2/comments/{id}
Content-Type: application/json

{
  "content": "Updated comment text"
}

Delete Comment

DELETE /todoist/rest/v2/comments/{id}

Returns 204 No Content.

Priority Values

Due Date Formats

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"

Code Examples

JavaScript

// Create a task
const response = await fetch('https://gateway.maton.ai/todoist/rest/v2/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();

Python

import os
import requests

# Create a task
response = requests.post(
    'https://gateway.maton.ai/todoist/rest/v2/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()

Notes

• Task IDs and Project IDs are strings, not integers
• Priority 4 is the highest (urgent), priority 1 is normal
• Use only one due date format per request (due_string, due_date, or due_datetime)
• Closing a recurring task schedules the next occurrence
• The Inbox project cannot be deleted
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Troubleshooting: Invalid API Key

When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'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))
EOF

Resources

• Todoist REST API v2 Documentation
• Todoist API v1 Documentation
• Todoist Filter Syntax
• Todoist OAuth Documentation