Maton

Todoist

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

Reference

List Projects

GET /todoist/api/v1/projects

Response:

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

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

Create Project

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:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'name': 'My New Project', 'color': 'blue'}).encode()
req = urllib.request.Request('https://api.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

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

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

Delete Project

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

Returns 204 No Content on success.

Get Project Collaborators

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

List Tasks

GET /todoist/api/v1/tasks

Query Parameters:

ParameterTypeDescription
project_idstringFilter by project
section_idstringFilter by section
labelstringFilter by label name
filterstringTodoist filter expression
idsstringComma-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 Task

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

Create Task

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:

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://api.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))
EOF

Update Task

POST /todoist/api/v1/tasks/{id}
Content-Type: application/json

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

Close Task (Complete)

POST /todoist/api/v1/tasks/{id}/close

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

Reopen Task

POST /todoist/api/v1/tasks/{id}/reopen

Returns 204 No Content.

Delete Task

DELETE /todoist/api/v1/tasks/{id}

Returns 204 No Content.

List Sections

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 Section

GET /todoist/api/v1/sections/{id}

Create Section

POST /todoist/api/v1/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/api/v1/sections/{id}
Content-Type: application/json

{
  "name": "Updated Section Name"
}

Delete Section

DELETE /todoist/api/v1/sections/{id}

Returns 204 No Content.

List Labels

GET /todoist/api/v1/labels

Response:

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

Get Label

GET /todoist/api/v1/labels/{id}

Create Label

POST /todoist/api/v1/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/api/v1/labels/{id}
Content-Type: application/json

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

Delete Label

DELETE /todoist/api/v1/labels/{id}

Returns 204 No Content.

List Comments

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 Comment

GET /todoist/api/v1/comments/{id}

Create Comment

POST /todoist/api/v1/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/api/v1/comments/{id}
Content-Type: application/json

{
  "content": "Updated comment text"
}

Delete Comment

DELETE /todoist/api/v1/comments/{id}

Returns 204 No Content.

Resources

PreviousTimeNextToggl Track

On this page

Reference
List Projects
Get Project
Create Project
Update Project
Delete Project
Get Project Collaborators
List Tasks
Get Task
Create Task
Update Task
Close Task (Complete)
Reopen Task
Delete Task
List Sections
Get Section
Create Section
Update Section
Delete Section
List Labels
Get Label
Create Label
Update Label
Delete Label
List Comments
Get Comment
Create Comment
Update Comment
Delete Comment
Resources