OVERVIEW
PJT AI REST API
用于将 PJT AI 数据与外部系统集成的标准 REST API。所有请求与响应均为 JSON，Base URL 为 https://api.pjt.ai/api/external/v1。
基础信息
- 认证 — X-API-Key 请求头（账号 API 密钥，pjt_ 前缀）
- 密钥范围 — read（只读，默认）/ write。POST·PUT·DELETE 需要 write 范围的密钥 — 否则返回 403 SCOPE_FORBIDDEN
- 请求限制 — 每密钥 60 次/分钟 + 每月 10,000 次（Enterprise 可协商）
- 响应码 — 2xx 成功、4xx 客户端错误、5xx 服务器错误
- 日期 — 所有时间戳均为 ISO 8601（UTC）
AUTH
认证
每个请求都需要 X-API-Key: <API_KEY> 请求头。密钥在 账号设置 > API 密钥 中签发（仅在创建时显示一次）。
密钥保管
API 密钥请仅在服务器端使用。一旦暴露给客户端（浏览器/移动应用），应立即吊销并重新签发。
Workspaces
GET
/workspaces工作区列表
返回 API 密钥账号可访问的工作区列表。
Response codes
200OK401Unauthorized429Rate Limited
GET
/workspaces/{workspaceId}查询工作区
查询单个工作区。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作区 ID |
Response codes
200OK401Unauthorized404Not Found
Projects
GET
/workspaces/{workspaceId}/projects项目列表
返回工作区的活跃项目列表（不含已取消/已归档）。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作区 ID |
Response codes
200OK401Unauthorized403Forbidden
POST
/projects创建项目（幂等）
创建项目。传入 externalRef 时为幂等操作 — 使用相同 (workspaceId, externalRef) 重复请求时不会新建，而是以 200 返回既有项目（首次创建为 201）。
Body parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作区 ID |
| nameREQUIRED | string | 项目名称 |
| externalRef | string | 幂等键 — 使用相同值重复请求时不会新建，而是以 200 返回既有项目 |
| code | string | 项目代码（任务键前缀）。省略时根据名称自动生成 |
| description | string | 描述 |
| clientIds | array | 客户 ID 数组 |
| managerId | integer | 负责经理的账号 ID |
| startDate | date | 开始日期 — ISO 8601 (YYYY-MM-DD) |
| endDate | date | 结束日期 — ISO 8601 (YYYY-MM-DD) |
| budget | integer | 预算 |
Response codes
201Created200OK400Bad Request401Unauthorized
GET
/projects/{projectId}项目详情 / 进度
返回项目详情，包含状态、进度(%)、计划/实际日程和最后修改时间。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Response codes
200OK404Not Found
PUT
/projects/{projectId}更新项目
仅更新传入的字段（部分更新）。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Body parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| name | string | 项目名称 |
| status | enum | 状态 — PLANNING·ESTIMATING·WAITING·IN_PROGRESS·ON_HOLD·COMPLETED·CANCELLED |
| progressRate | integer | 进度(%) 0~100 |
| startDate | date | 开始日期 — ISO 8601 (YYYY-MM-DD) |
| endDate | date | 结束日期 — ISO 8601 (YYYY-MM-DD) |
Response codes
200OK400Bad Request404Not Found
DELETE
/projects/{projectId}删除项目
删除项目。成功时返回 204 No Content（无响应体）。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Response codes
204No Content403Forbidden404Not Found
GET
/projects/{projectId}/timeline时间线（里程碑）
项目里程碑列表 — 名称、状态（PLANNED/IN_PROGRESS/COMPLETED）、截止日期、完成日期和进度。按 sortOrder 排序返回。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Response codes
200OK403Forbidden404Not Found
GET
/projects/{projectId}/activities活动记录
按最新顺序返回项目的任务变更事件 — 类型、消息、操作者和时间。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Query parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| page | integer | 页码（从 0 开始，默认 0） |
| size | integer | 每页数量（默认 50，最大 200） |
Response codes
200OK403Forbidden404Not Found
GET
/projects/{projectId}/files文件列表
合并返回项目内任务和评论的附件，按最新排序。fileUrl 为不过期的静态 URL。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Query parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| limit | integer | 最大数量（默认 100，最大 500） |
Response codes
200OK403Forbidden404Not Found
Tasks
GET
/projects/{projectId}/tasks任务列表
返回项目的任务列表。需要分页时请使用 /tasks/paged。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Query parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| sortBy | string | 排序字段（默认 createdAt） |
Response codes
200OK403Forbidden404Not Found
POST
/tasks创建任务
创建任务。
Body parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | integer | 项目 ID（数字） |
| titleREQUIRED | string | 标题 |
| description | string | 描述 |
| assigneeId | integer | 负责人账号 ID |
| status | enum | 状态 — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | 优先级 — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | 截止日期 — ISO 8601 |
| milestoneId | integer | 要关联的里程碑 ID |
Response codes
201Created400Bad Request401Unauthorized
GET
/tasks/{taskId}查询任务
查询单个任务。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| taskIdREQUIRED | integer | 任务 ID |
Response codes
200OK404Not Found
PUT
/tasks/{taskId}更新任务
仅更新传入的字段。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| taskIdREQUIRED | integer | 任务 ID |
Body parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| title | string | 标题 |
| status | enum | 状态 — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | 优先级 — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | 截止日期 — ISO 8601 |
Response codes
200OK400Bad Request404Not Found
DELETE
/tasks/{taskId}删除任务
删除任务。成功时返回 204 No Content。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| taskIdREQUIRED | integer | 任务 ID |
Response codes
204No Content403Forbidden404Not Found
GET
/tasks/assigned我的任务
返回分配给 API 密钥账号的任务列表。
Response codes
200OK401Unauthorized
Documents
GET
/projects/{projectId}/documents文档列表
返回项目的文档列表。需要分页时请使用 /documents/paged。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| projectIdREQUIRED | string | 项目 ID — 数字 ID 或以 p_ 开头的 publicId |
Response codes
200OK403Forbidden404Not Found
GET
/documents/{documentId}查询文档
查询单个文档（含正文）。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| documentIdREQUIRED | integer | 文档 ID |
Response codes
200OK404Not Found
POST
/documents创建文档
创建文档。
Body parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作区 ID |
| titleREQUIRED | string | 标题 |
| documentTypeREQUIRED | enum | 文档类型（如 REQUIREMENT, MEETING_NOTE） |
| projectId | integer | 项目 ID（数字） |
| content | string | 文档正文 |
| visibility | enum | 可见范围 — PUBLIC·TEAM·PRIVATE |
Response codes
201Created400Bad Request401Unauthorized
PUT
/documents/{documentId}更新文档
仅更新传入的字段。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| documentIdREQUIRED | integer | 文档 ID |
Body parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| title | string | 标题 |
| content | string | 文档正文 |
| visibility | enum | 可见范围 — PUBLIC·TEAM·PRIVATE |
Response codes
200OK400Bad Request404Not Found
DELETE
/documents/{documentId}删除文档
删除文档。成功时返回 204 No Content。
Path parameters
| 名称 | 类型 | 说明 |
|---|---|---|
| documentIdREQUIRED | integer | 文档 ID |
Response codes
204No Content403Forbidden404Not Found
ERRORS
错误码
所有错误响应都包含 error.code 和 error.message。
| 代码 | 名称 | 说明 | 处理 |
|---|---|---|---|
| 400 | Bad Request | 请求体无效。 | 校验请求 body |
| 401 | Unauthorized | API 密钥错误或缺失。 | 重新确认 API 密钥 |
| 403 | Forbidden | 没有访问该资源的权限。 使用只读密钥发送写入请求时会返回 SCOPE_FORBIDDEN。 | 检查角色/作用域 |
| 404 | Not Found | 未找到请求的资源。 | 重新确认 ID |
| 429 | Rate Limited | 已超过请求限制。 | 参考 Retry-After 头并应用退避 |
| 500 | Server Error | 服务器处理时发生错误。 | 5 分钟后重试，查看 status.pjt.ai |