基础 URL

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

将 {native-api-path} 替换为实际的 Toggl Track API 端点路径。网关会将请求代理到 api.track.toggl.com 并自动注入您的凭证。

认证

所有请求都需要在 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 管理您的 Toggl Track OAuth 连接。

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=toggl-track&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: toggl-track}).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: 0acc2145-4d3e-4eaf-bdfd-7b04e0e0d649,
status: ACTIVE,
creation_time: 2026-02-13T19:31:31.452264Z,
lastupdatedtime: 2026-02-13T19:36:10.489069Z,
url: https://connect.maton.ai/?session_token=...,
app: toggl-track,
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

指定连接

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

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/toggl-track/api/v9/me)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Maton-Connection, 0acc2145-4d3e-4eaf-bdfd-7b04e0e0d649)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

API 参考

用户与工作区

获取当前用户

bash
GET /toggl-track/api/v9/me

响应：
json
{
id: 12932942,
email: user@example.com,
fullname: John Doe,
timezone: America/Los_Angeles,
defaultworkspaceid: 21180405,
beginningofweek: 1,
image_url: https://assets.track.toggl.com/images/profile.png
}

列出工作区

bash
GET /toggl-track/api/v9/me/workspaces

获取工作区

bash
GET /toggl-track/api/v9/workspaces/{workspace_id}

列出工作区用户

bash
GET /toggl-track/api/v9/workspaces/{workspace_id}/users

时间条目

列出时间条目

bash
GET /toggl-track/api/v9/me/time_entries

查询参数：

• - since（整数）- 在此时间之后修改的条目的 UNIX 时间戳
• before（字符串）- 获取此日期之前的条目（RFC3339 或 YYYY-MM-DD）
• startdate（字符串）- 过滤开始日期（YYYY-MM-DD）
• enddate（字符串）- 过滤结束日期（YYYY-MM-DD）

获取当前（运行中的）时间条目

bash
GET /toggl-track/api/v9/me/time_entries/current

如果没有正在运行的时间条目，则返回 null。

按 ID 获取时间条目

bash
GET /toggl-track/api/v9/me/timeentries/{timeentry_id}

创建时间条目

bash
POST /toggl-track/api/v9/workspaces/{workspaceid}/timeentries
Content-Type: application/json

{
description: Working on project,
start: 2026-02-13T10:00:00Z,
duration: -1,
workspace_id: 21180405,
project_id: 216896134,
tag_ids: [20053808],
created_with: maton-api
}

注意： 将 duration 设置为 -1 以启动运行中的计时器。created_with 字段是必需的。

响应：
json
{
id: 4290254971,
workspace_id: 21180405,
project_id: null,
task_id: null,
billable: false,
start: 2026-02-13T19:58:43Z,
stop: null,
duration: -1,
description: Working on project,
tags: null,
tag_ids: null,
user_id: 12932942
}

更新时间条目

bash
PUT /toggl-track/api/v9/workspaces/{workspaceid}/timeentries/{timeentryid}
Content-Type: application/json

{
description: Updated description,
project_id: 216896134
}

停止运行中的时间条目

bash
PATCH /toggl-track/api/v9/workspaces/{workspaceid}/timeentries/{timeentryid}/stop

删除时间条目

bash
DELETE /toggl-track/api/v9/workspaces/{workspaceid}/timeentries/{timeentryid}

项目

列出项目

bash
GET /toggl-track/api/v9/workspaces/{workspace_id}/projects

查询参数：

• - active（布尔值）- 按活动状态过滤
• since（整数）- 修改过滤的 UNIX 时间戳
• name（字符串）- 按项目名称过滤
• page（整数）- 页码
• per_page（整数）- 每页项目数（最多 200）

获取项目

bash
GET /toggl-track/api/v9/workspaces/{workspaceid}/projects/{projectid}

创建项目

bash
POST /toggl-track/api/v9/workspaces/{workspace_id}/projects
Content-Type: application/json