基础 URL

https://gateway.maton.ai/todoist/api/v1/{resource}

该网关将请求代理到 api.todoist.com/api/v1，并自动注入您的 OAuth 令牌。

认证

所有请求都需要在 Authorization 头中携带 Maton API 密钥：

Authorization: Bearer $MATONAPIKEY

环境变量： 将您的 API 密钥设置为 MATONAPIKEY：

bash
export MATONAPIKEY=YOURAPIKEY

获取您的 API 密钥

1. 1. 在 maton.ai 登录或创建账户
2. 前往 maton.ai/settings
3. 复制您的 API 密钥

连接管理

在 https://ctrl.maton.ai 管理您的 Todoist OAuth 连接。

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=todoist&status=ACTIVE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建连接

bash
python < 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.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

获取连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id})
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应：
json
{
connection: {
connection_id: 21fd90f9-5935-43cd-b6c8-bde9d915ca80,
status: ACTIVE,
creation_time: 2025-12-08T07:20:53.488460Z,
lastupdatedtime: 2026-01-31T20:03:32.593153Z,
url: https://connect.maton.ai/?session_token=...,
app: todoist,
metadata: {}
}
}

在浏览器中打开返回的 url 以完成 OAuth 授权。

删除连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections/{connection_id}, method=DELETE)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

指定连接

如果您有多个 Todoist 连接，请使用 Maton-Connection 头指定要使用的连接：

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/todoist/api/v1/tasks)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Maton-Connection, 21fd90f9-5935-43cd-b6c8-bde9d915ca80)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早）的活动连接。

API 参考

项目

列出项目

bash
GET /todoist/api/v1/projects

响应：
json
{
results: [
{
id: 6fwFRqmVCFvWVX5R,
name: 收件箱,
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
}

获取项目

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

创建项目

bash
POST /todoist/api/v1/projects
Content-Type: application/json

{
name: 我的项目,
color: blue,
is_favorite: true,
view_style: board
}

参数：

• - name（必填）- 项目名称
• parentid - 父项目 ID，用于嵌套
• color - 项目颜色（例如 red、blue、green）
• isfavorite - 布尔值收藏状态
• view_style - list 或 board（默认：list）

示例：
bash
python < import urllib.request, os, json
data = json.dumps({name: 我的新项目, color: blue}).encode()
req = urllib.request.Request(https://gateway.maton.ai/todoist/api/v1/projects, data=data, method=POST)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Content-Type, application/json)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

更新项目

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

{
name: 更新后的项目名称,
color: red
}

删除项目

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

成功时返回 204 No Content。

获取项目协作者

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

任务

列出任务

bash
GET /todoist/api/v1/tasks

查询参数：

响应：
json
{
results: [
{
id: 6fwhG9wMHr4wxgpR,
content: 购买杂货,
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: 明天上午10点,
lang: en,
is_recurring: false
},
added_at: 2026-02-06T20:41:08.449320Z
}
],
next_cursor: null
}

获取任务

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

创建任务

bash
POST /todoist/api/v1/tasks
Content-Type: application/json

{
content: 购买杂货,
project_id: 2366834771,
priority: 2,
due_string: 明天上午10点,
labels: [购物, 差事]
}

必填字段：

• - content - 任务内容/标题

可选字段：

• - description - 任务描述
• projectid - 添加任务的项目（默认为收件箱）
• sectionid - 项目内的分区
• parent_id - 父任务