TickTick

通过托管的OAuth认证访问TickTick API。通过完整的CRUD操作管理任务和项目。

快速开始

# List all projects
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/ticktick/open/v1/project')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/ticktick/{native-api-path}

网关将请求代理至api.ticktick.com并自动注入您的OAuth令牌。

认证

所有请求都要求在Authorization头部中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

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

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

1. 请登录或前往maton.ai
2. 创建一个账户前往
3. maton.ai/settings

复制您的API密钥

连接管理请在https://ctrl.maton.ai

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=ticktick&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

创建连接

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'ticktick'}).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

获取连接

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

响应：

{
  "connection": {
    "connection_id": "1fd9c3aa-6b46-456f-aa21-ed154de23ab7",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T09:55:40.786711Z",
    "last_updated_time": "2026-02-07T09:56:30.403237Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "ticktick",
    "metadata": {}
  }
}

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

删除连接

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

指定连接

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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/ticktick/open/v1/project')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '1fd9c3aa-6b46-456f-aa21-ed154de23ab7')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

API 参考

项目操作

列出项目

GET /ticktick/open/v1/project

响应：

[
  {
    "id": "6984773291819e6d58b746a8",
    "name": "🏡Memo",
    "sortOrder": 0,
    "viewMode": "list",
    "kind": "TASK"
  },
  {
    "id": "6984773291819e6d58b746a9",
    "name": "🦄Wishlist",
    "sortOrder": -1099511627776,
    "viewMode": "list",
    "kind": "TASK"
  }
]

获取包含任务的项目

GET /ticktick/open/v1/project/{projectId}/data

响应：

{
  "project": {
    "id": "69847732b8e5e969f70e7460",
    "name": "👋Welcome",
    "sortOrder": -3298534883328,
    "viewMode": "list",
    "kind": "TASK"
  },
  "tasks": [
    {
      "id": "69847732b8e5e969f70e7464",
      "projectId": "69847732b8e5e969f70e7460",
      "title": "Sample task",
      "content": "Task description",
      "priority": 0,
      "status": 0,
      "tags": [],
      "isAllDay": false
    }
  ],
  "columns": [
    {
      "id": "69847732b8e5e969f70e7463",
      "projectId": "69847732b8e5e969f70e7460",
      "name": "Getting Start",
      "sortOrder": -2199023255552
    }
  ]
}

创建项目

POST /ticktick/open/v1/project
Content-Type: application/json

{
  "name": "My New Project",
  "viewMode": "list"
}

响应：

{
  "id": "69870cbe8f08b4a6770a38d3",
  "name": "My New Project",
  "sortOrder": 0,
  "viewMode": "list",
  "kind": "TASK"
}

viewMode 选项：

• 列表- 列表视图
• 看板- 看板视图
• 时间线- 时间线视图

删除项目

DELETE /ticktick/open/v1/project/{projectId}

成功时返回空响应（状态码 200）。

任务操作

获取任务

GET /ticktick/open/v1/project/{projectId}/task/{taskId}

响应：

{
  "id": "69847732b8e5e969f70e7464",
  "projectId": "69847732b8e5e969f70e7460",
  "sortOrder": -1099511627776,
  "title": "Task title",
  "content": "Task description/notes",
  "timeZone": "Asia/Shanghai",
  "isAllDay": true,
  "priority": 0,
  "status": 0,
  "tags": [],
  "columnId": "69847732b8e5e969f70e7461",
  "etag": "2sayfdsh",
  "kind": "TEXT"
}

创建任务

POST /ticktick/open/v1/task
Content-Type: application/json

{
  "title": "New task",
  "projectId": "6984773291819e6d58b746a8",
  "content": "Task description",
  "priority": 0,
  "dueDate": "2026-02-15T10:00:00+0000",
  "isAllDay": false
}

响应：

{
  "id": "69870cb08f08b86b38951175",
  "projectId": "6984773291819e6d58b746a8",
  "sortOrder": -1099511627776,
  "title": "New task",
  "timeZone": "America/Los_Angeles",
  "isAllDay": false,
  "priority": 0,
  "status": 0,
  "tags": [],
  "etag": "gl7ibhor",
  "kind": "TEXT"
}

优先级值：

• 0- 无
• 1- 低
• 3- 中
• 5- 高

更新任务

POST /ticktick/open/v1/task/{taskId}
Content-Type: application/json

{
  "id": "69870cb08f08b86b38951175",
  "projectId": "6984773291819e6d58b746a8",
  "title": "Updated task title",
  "priority": 1
}

响应：

{
  "id": "69870cb08f08b86b38951175",
  "projectId": "6984773291819e6d58b746a8",
  "title": "Updated task title",
  "priority": 1,
  "status": 0,
  "etag": "hmb7uk8c",
  "kind": "TEXT"
}

完成任务

POST /ticktick/open/v1/project/{projectId}/task/{taskId}/complete

成功时返回空响应（状态码 200）。

删除任务

DELETE /ticktick/open/v1/project/{projectId}/task/{taskId}

成功时返回空响应（状态码 200）。

任务字段

代码示例

JavaScript

// List all projects
const response = await fetch(
  'https://gateway.maton.ai/ticktick/open/v1/project',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const projects = await response.json();

// Create a task
const createResponse = await fetch(
  'https://gateway.maton.ai/ticktick/open/v1/task',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      title: 'New task',
      projectId: 'PROJECT_ID'
    })
  }
);

Python

import os
import requests

# List all projects
response = requests.get(
    'https://gateway.maton.ai/ticktick/open/v1/project',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
projects = response.json()

# Create a task
response = requests.post(
    'https://gateway.maton.ai/ticktick/open/v1/task',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'New task',
        'projectId': 'PROJECT_ID'
    }
)

备注

• Open API 仅提供对任务和项目的访问
• 习惯、专注/番茄钟和标签功能无法通过开放API使用
• 任务状态取值：0 = 进行中，2 = 已完成
• 优先级取值：0 = 无，1 = 低，3 = 中，5 = 高
• 日期采用带时区偏移的ISO 8601格式（例如2026-02-15T10:00:00+0000）
• 视图模式适用于项目：列表、看板或时间轴
• 项目数据中的列字段用于看板列
• 重要提示：将curl输出通过管道传递给jq或其他命令时，某些Shell环境中$MATON_API_KEY这类环境变量可能无法正确展开

错误处理

故障排除：API密钥问题

1. 检查是否已设置MATON_API_KEY环境变量：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

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

故障排除：无效应用名称

1. 请确保您的URL路径以ticktick开头。例如：

• 正确示例：https://gateway.maton.ai/ticktick/open/v1/project
• 不正确https://gateway.maton.ai/open/v1/project

资源

• TickTick 开发者门户
• TickTick 帮助中心
• Maton 社区
• Maton 技术支持