介绍
# Basecamp
通过受管理的 OAuth 身份验证访问 Basecamp 4 API。管理项目、待办事项、消息、日程、文档和团队协作。
## 快速开始
```bash # List all projects python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/basecamp/projects.json') 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/basecamp/{resource}.json ```
网关将请求代理到 `3.basecampapi.com/{account_id}/`，并自动注入您的 OAuth 令牌和账户 ID。
**重要提示：** 所有 Basecamp API URL 必须以 `.json` 结尾。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 访问 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Basecamp OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=basecamp&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 ```
### 创建连接
```bash python <<'EOF' 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.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 ```
### 获取连接
```bash 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 ```
**响应：** ```json { "connection": { "connection_id": "71e313c8-9100-48c6-8ea1-6323f6fafd04", "status": "ACTIVE", "creation_time": "2026-02-08T03:12:39.815086Z", "last_updated_time": "2026-02-08T03:12:59.259878Z", "url": "https://connect.maton.ai/?session_token=...", "app": "basecamp", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash 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 ```
### 指定连接
如果您有多个 Basecamp 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/basecamp/projects.json') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_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": "[email protected]", "admin": true, "owner": true, "time_zone": "America/Los_Angeles", "avatar_url": "https://..." } ```
### 人员操作
#### 列出人员
```bash GET /basecamp/people.json ```
**响应：** ```json [ { "id": 51197030, "name": "Chris Kim", "email_address": "[email protected]", "admin": true, "owner": true, "employee": true, "time_zone": "America/Los_Angeles" } ] ```
#### 获取人员
```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 中获取 todoset ID：
```bash GET /basecamp/buckets/{project_id}/todosets/{todoset_id}.json ```
#### 列出待办清单
```bash GET /basecamp/buckets/{project_id}/todosets/{todoset_id}/todolists.json ```
**响应：** ```json [ { "id": 9550474442, "title": "Basecamp essentials", "description": "", "completed": false, "completed_ratio": "0/5", "url": "https://..." } ] ```
#### 创建待办清单
```bash POST /basecamp/buckets/{project_id}/todosets/{todoset_id}/todolists.json Content-Type: application/json
{ "name": "New Todo List", "description": "List description" } ```
#### 获取待办清单
```bash GET /basecamp/buckets/{project_id}/todolists/{todolist_id}.json ```
#### 列出待办事项
```bash GET /basecamp/buckets/{project_id}/todolists/{todolist_id}/todos.json ```
**响应：** ```json [ { "id": 9550474446, "content": "Start here", "description": "", "completed": false, "due_on": null, "assignees": [] } ] ```
#### 创建待办事项
```bash POST /basecamp/buckets/{project_id}/todolists/{todolist_id}/todos.json Content-Type: application/json
{ "content": "New todo item", "description": "Todo description", "due_on": "2026-02-15", "assignee_ids": [51197030] } ```
**响应：** ```json { "id": 9555973289, "content": "New todo item", "completed": false } ```
#### 更新待办事项
```bash PUT /basecamp/buckets/{project_id}/todos/{todo_id}.json Content-Type: application/json
{ "content": "Updated todo", "description": "Updated description" } ```
#### 完成待办事项
```bash POST /basecamp/buckets/{project_id}/todos/{todo_id}/completion.json ```
成功时返回 204。
#### 标记待办事项为未完成
```bash DELETE /basecamp/buckets/{project_id}/todos/{todo_id}/completion.json ```
### 消息板操作
#### 获取消息板
```bash GET /basecamp/buckets/{project_id}/message_boards/{message_board_id}.json ```
#### 列出消息
```bash GET /basecamp/buckets/{project_id}/message_boards/{message_board_id}/messages.json ```
#### 创建消息
```bash POST /basecamp/buckets/{project_id}/message_boards/{message_board_id}/messages.json Content-Type: application/json
{ "subject": "Message Subject", "content": "<p>Message body with HTML</p>", "category_id": 123 } ```
#### 获取消息
```bash GET /basecamp/buckets/{project_id}/messages/{message_id}.json ```
#### 更新消息
```bash PUT /basecamp/buckets/{project_id}/messages/{message_id}.json Content-Type: application/json
{ "subject": "Updated Subject", "content": "<p>Updated content</p>" } ```
### 日程操作
#### 获取日程
```bash GET /basecamp/buckets/{project_id}/schedules/{schedule_id}.json ```
#### 列出日程条目
```bash GET /basecamp/buckets/{project_id}/schedules/{schedule_id}/entries.json ```
#### 创建日程条目
```bash POST /basecamp/buckets/{project_id}/schedules/{schedule_id}/entries.json Content-Type: application/json
{ "summary": "Team Meeting", "description": "Weekly sync", "starts_at": "2026-02-15T14:00:00Z", "ends_at": "2026-02-15T15:00:00Z", "all_day": false, "participant_ids": [51197030] } ```
#### 更新日程条目
```bash PUT /basecamp/buckets/{project_id}/schedule_entries/{entry_id}.json Content-Type: application/json
{ "summary": "Updated Meeting", "starts_at": "2026-02-15T15:00:00Z", "ends_at": "2026-02-15T16:00:00Z" } ```
### 保险库（文档和文件）操作
#### 获取保险库
```bash GET /basecamp/buckets/{project_id}/vaults/{vault_id}.json ```
#### 列出保险库中的文档
```bash GET /basecamp/buckets/{project_id}/vaults/{vault_id}/documents.json ```
#### 创建文档
```bash POST /basecamp/buckets/{project_id}/vaults/{vault_id}/documents.json Content-Type: application/json
{ "title": "Document Title", "content": "<p>Document content with HTML</p>" } ```
#### 列出保险库中的上传项
```bash GET /basecamp/buckets/{project_id}/vaults/{vault_id}/uploads.json ```
### Campfire（聊天）操作
#### 列出所有 Campfire
```bash GET /basecamp/chats.json ```
#### 获取 Campfire
```bash GET /basecamp/buckets/{project_id}/chats/{chat_id}.json ```
#### 列出 Campfire 记录（消息）
```bash GET /basecamp/buckets/{project_id}/chats/{chat_id}/lines.json ```
#### 创建 Campfire 记录
```bash POST /basecamp/buckets/{project_id}/chats/{chat_id}/lines.json Content-Type: application/json
{ "content": "Hello from the API!" } ```
### 评论操作
#### 列出记录的评论
```bash GET /basecamp/buckets/{project_id}/recordings/{recording_id}/comments.json ```
#### 创建评论
```bash POST /basecamp/buckets/{project_id}/recordings/{recording_id}/comments.json Content-Type: application/json
{ "content": "<p>Comment text</p>" } ```
### 记录状态操作
所有内容项（待办事项、消息、文档等）都是可以存档或放入回收站的“记录”。
#### 将记录放入回收站
```bash PUT /basecamp/buckets/{project_id}/recordings/{recording_id}/status/trashed.json ```
#### 存档记录
```bash PUT /basecamp/buckets/{project_id}/recordings/{recording_id}/status/archived.json ```
#### 取消存档记录
```bash PUT /basecamp/buckets/{project_id}/recordings/{recording_id}/status/active.json ```
### 模板操作
#### 列出模板
```bash GET /basecamp/templates.json ```
#### 从模板创建项目
```bash POST /basecamp/templates/{template_id}/project_constructions.json Content-Type: application/json
{ "name": "New Project from Template", "description": "Description" } ```
## 分页
Basecamp 使用带有 `rel="next"` 的 Link 标头进行分页：
**响应标头：** ``` Link: <https://3.basecampapi.com/.../page=2>; rel="next" X-Total-Count: 150 ```
请跟随 `Link` 标头 URL 中的下一页链接。当 `next` 不存在时，表示您已到达最后一页。
**重要提示：** 请勿手动构建分页 URL。始终使用 `Link` 标头中提供的 URL。
## 核心概念
### 存储桶和项目
“存储桶”是项目的内容容器。存储桶 ID 与 URL 中的项目 ID 相同：
``` /buckets/{project_id}/todosets/{todoset_id}.json ```
### Dock
每个项目都有一个包含可用工具的“dock”。在使用工具之前，请始终检查该工具是否为 `enabled: true`：
```json { "dock": [ {"name": "todoset", "id": 123, "enabled": true}, {"name": "message_board", "id": 456, "enabled": false} ] } ```
### 记录
所有内容项（待办事项、消息、文档、评论等）都是“记录”，具有： - `status`：“active”（活跃）、“archived”（已存档）或“trashed”（已删除） - `parent`：指向容器的导航 - 可在各个端点使用的唯一 ID
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/basecamp/projects.json', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const projects = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/basecamp/projects.json', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) projects = response.json() ```
## 注意事项
- 所有 API 路径必须以 `.json` 结尾 - 网关会自动注入账户 ID - 使用 Basecamp 4 API (bc3-api) - 时间戳采用 ISO 8601 格式 - HTML 内容使用 `<div>`、`<p>`、`<strong>`、`<em>`、`<a>`、`<ul>`、`<ol>`、`<li>` 标签 - 速率限制：每个 IP 每 10 秒约 50 个请求 - 重要提示：当将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Basecamp 连接或请求错误 | | 401 | Maton API 密钥无效或缺失 | | 404 | 资源未找到、已删除或无权访问 | | 429 | 速率受限（检查 Retry-After 标头） | | 507 | 已达到账户限制（例如项目限制） | | 5xx | 服务器错误（请使用指数退避重试） |
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash 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 路径以 `basecamp` 开头。例如：
- 正确：`https://gateway.maton.ai/basecamp/projects.json` - 错误：`https://gateway.maton.ai/projects.json`
## 资源
- [Basecamp 4 API 文档](https://github.com/basecamp/bc3-api) - [身份验证指南](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md) - [API 参考](https://github.com/basecamp/bc3-api#endpoints) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])