基础 URL

https://gateway.maton.ai/basecamp/{resource}.json

该网关将请求代理到 3.basecampapi.com/{account_id}/，并自动注入您的 OAuth 令牌和账户 ID。

重要提示： 所有 Basecamp API URL 必须以 .json 结尾。

认证

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

列出连接

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://ctrl.maton.ai/connections?app=basecamp&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: basecamp}).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: 71e313c8-9100-48c6-8ea1-6323f6fafd04,
status: ACTIVE,
creation_time: 2026-02-08T03:12:39.815086Z,
lastupdatedtime: 2026-02-08T03:12:59.259878Z,
url: https://connect.maton.ai/?session_token=...,
app: basecamp,
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

指定连接

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

bash
python < import urllib.request, os, json
req = urllib.request.Request(https://gateway.maton.ai/basecamp/projects.json)
req.addheader(Authorization, fBearer {os.environ[MATONAPI_KEY]})
req.add_header(Maton-Connection, 71e313c8-9100-48c6-8ea1-6323f6fafd04)
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

API 参考

用户信息

获取当前用户

bash
GET /basecamp/my/profile.json

响应：
json
{
id: 51197030,
name: Chris Kim,
email_address: chris@example.com,
admin: true,
owner: true,
timezone: America/LosAngeles,
avatar_url: https://...
}

人员操作

列出人员

bash
GET /basecamp/people.json

响应：
json
[
{
id: 51197030,
name: Chris Kim,
email_address: chris@example.com,
admin: true,
owner: true,
employee: true,
timezone: America/LosAngeles
}
]

获取人员

bash
GET /basecamp/people/{person_id}.json

列出项目成员

bash
GET /basecamp/projects/{project_id}/people.json

项目操作

列出项目

bash
GET /basecamp/projects.json

响应：
json
[
{
id: 46005636,
status: active,
name: Getting Started,
description: Quickly get up to speed with everything Basecamp,
created_at: 2026-02-05T22:59:26.087Z,
url: https://3.basecampapi.com/6153810/projects/46005636.json,
dock: [...]
}
]

获取项目

bash
GET /basecamp/projects/{project_id}.json

项目响应包含一个 dock 数组，其中包含可用的工具（message_board、todoset、vault、chat、schedule 等）。每个 dock 项包含：

• - id：工具的 ID
• name：工具类型（例如 todoset、message_board）
• enabled：工具是否处于活动状态
• url：访问工具的直接 URL

创建项目

bash
POST /basecamp/projects.json
Content-Type: application/json

{
name: New Project,
description: Project description
}

更新项目

bash
PUT /basecamp/projects/{project_id}.json
Content-Type: application/json

{
name: Updated Project Name,
description: Updated description
}

删除（归档）项目

bash
DELETE /basecamp/projects/{project_id}.json

待办事项操作

获取待办事项集

首先，从项目的 dock 中获取待办事项集 ID：

bash
GET /basecamp/buckets/{projectid}/todosets/{todosetid}.json

列出待办事项列表

bash
GET /basecamp/buckets/{projectid}/todosets/{todosetid}/todolists.json

响应：
json
[
{
id: 9550474442,
title: Basecamp essentials,
description: ,
completed: false,
completed_ratio: 0/5,
url: https://...
}
]

创建待办事项列表

bash
POST /basecamp/buckets/{projectid}/todosets/{todosetid}/todolists.json
Content-Type: application/json

{
name: New Todo List,
description: List description
}

获取待办事项列表

bash
GET /basecamp/buckets/{projectid}/todolists/{todolistid}.json

列出待办事项

bash
GET /basecamp/buckets/{projectid}/todolists/{todolistid}/todos.json

响应：
json
[
{
id: 9550474446,
content: Start here,
description: ,
completed: false,
due_on: null,
assignees: []
}
]

创建待办事项

bash
POST /basecamp/buckets/{projectid}/todolists/{todolistid}/todos.json
Content-Type: application/json

{
content: New todo item,