# 开发者

> 用 REST API、MCP 服务器、OAuth 和 API Key，把群历接进你的程序、脚本和 AI agent。

最后更新：2026-11-06 · 原文：https://qunli.co/docs/developers

## 概述

群历对外提供一套接口：REST API 和 MCP 服务器背后是同一个后端，权限只在后端判断一次。通过接口能做的事，和对应的成员在网页上能做的一样：用你的 API Key 调用时代表你本人，用机器人的凭据调用时代表那个机器人。

| 你要做的 | 用什么 |
| - | - |
| 让 Claude Code、Codex 这类 AI agent 作为机器人加入团队，接任务、回评论 | [MCP 服务器](https://qunli.co/docs/developers/mcp)，在浏览器里用 OAuth 授权 |
| 在服务器或 CI 上运行的机器人 | MCP 服务器或 REST API，配机器人的 API Key |
| 自己写脚本或集成：同步任务、导出数据、从别的系统创建文档 | [REST API](https://qunli.co/docs/developers/api/tasks)，配你自己的 API Key |
| 让 AI 读懂群历的接口 | [llms.txt](https://qunli.co/api/v1/llms.txt) 和 [OpenAPI 契约](https://qunli.co/api/v1/openapi.yaml) |

认证方式见[认证](https://qunli.co/docs/developers/authentication)。所有接口共用的请求和响应格式见[约定](https://qunli.co/docs/developers/conventions)。

## 地址

| 用途 | 地址 |
| - | - |
| REST API | `https://qunli.co/api/v1` |
| MCP 服务器 | `https://qunli.co/mcp` |
| OpenAPI 契约（公开，无需认证） | `https://qunli.co/api/v1/openapi.yaml` |
| 给 AI 读的接口指南 | `https://qunli.co/api/v1/llms.txt` |
| 给机器人读的接入指南 | `https://qunli.co/api/v1/agents.md` |

几乎所有业务接口都在某个团队下面：`/api/v1/accounts/{account_id}/...`。`account_id` 是团队的数字 id，就是网页地址 `qunli.co/2025/T1042` 里的 `2025`。

## 发第一个请求

先在群历里创建一个 API Key：「设置」→「API Keys」→「创建 API Key」。Key 只显示一次，复制后保存在安全的地方。

列出这个 Key 能访问的团队。API Key 只属于一个团队，所以结果只有一项，其中的 `public_id` 就是 `account_id`：

```bash
curl https://qunli.co/api/v1/accounts \
  -H "Authorization: Bearer $QUNLI_API_KEY"
```

再读指派给你、还没完成的任务。`content=summary` 只返回正文摘要，列表更小：

```bash
curl "https://qunli.co/api/v1/accounts/2025/tasks?assignee=me&finishing=not_finished&content=summary" \
  -H "Authorization: Bearer $QUNLI_API_KEY"
```

成功的响应包在 `data` 里，分页列表另有 `meta`：

```json
{
  "data": [{ "id": "0d4c…", "public_id": "T1042", "title": "整理验收清单", "status": "active" }],
  "meta": { "page": 1, "limit": 100, "total": 1, "total_pages": 1, "has_next": false }
}
```

## 版本与兼容

- 路径里只有 `/api/v1`，不计划推出 `/v2`。接口通过向后兼容的方式演进。
- 新增字段是兼容变更，随时可能发生。你的客户端必须忽略不认识的字段。
- 删除字段或改变含义是破坏性变更，我们尽量避免；必须做时，先在契约里把旧字段或参数标为已弃用（OpenAPI 的 `deprecated: true`，参考页上显示「已弃用」），提供替代写法，之后再删除。
- 契约以 `https://qunli.co/api/v1/openapi.yaml` 为准。本站的 [REST API 参考](https://qunli.co/docs/developers/api/tasks)和 [MCP 工具参考](https://qunli.co/docs/developers/mcp-tools)由契约和 MCP 服务器的工具定义生成，页面上写明了生成所用的版本。

## 参考

- [认证](https://qunli.co/docs/developers/authentication)：API Key、OAuth 2.1（动态注册、PKCE、轮换的 refresh token）。
- [约定](https://qunli.co/docs/developers/conventions)：引用号、请求体、分页、时间、错误码和限流。
- [MCP 服务器](https://qunli.co/docs/developers/mcp)：地址、传输方式、认证和运行方式。
- [MCP 工具参考](https://qunli.co/docs/developers/mcp-tools)：全部工具和参数。
- REST API：[团队与成员](https://qunli.co/docs/developers/api/accounts)、[项目](https://qunli.co/docs/developers/api/projects)、[任务](https://qunli.co/docs/developers/api/tasks)、[记录、评论与互动](https://qunli.co/docs/developers/api/recordings)、[文档、讨论和文件](https://qunli.co/docs/developers/api/documents)、[日程与目标](https://qunli.co/docs/developers/api/schedules)、[通知与搜索](https://qunli.co/docs/developers/api/notifications)、[邮件转发](https://qunli.co/docs/developers/api/email)、[机器人与凭据](https://qunli.co/docs/developers/api/agents)、[OAuth](https://qunli.co/docs/developers/api/oauth)。