OVERVIEW
PJT AI REST API
用於將 PJT AI 資料與外部系統整合的標準 REST API。所有的請求與回應皆為 JSON，基底網址為 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 金鑰帳號可存取的工作區列表。
回應碼
200OK401Unauthorized429Rate Limited
GET
/workspaces/{workspaceId}查詢工作區
查詢單一工作區。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作區 ID |
回應碼
200OK401Unauthorized404Not Found
Projects
GET
/workspaces/{workspaceId}/projects專案列表
回傳工作區的進行中專案列表（不含已取消/已封存）。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作區 ID |
回應碼
200OK401Unauthorized403Forbidden
POST
/projects建立專案（冪等）
建立專案。傳入 externalRef 時為冪等操作 — 以相同 (workspaceId, externalRef) 重複請求時不會新建，而是以 200 回傳既有專案（首次建立為 201）。
主體參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| 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 | 預算 |
回應碼
201Created200OK400Bad Request401Unauthorized
GET
/projects/{projectId}專案詳情 / 進度
回傳專案詳情，包含狀態、進度(%)、計畫/實際日程與最後修改時間。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
回應碼
200OK404Not Found
PUT
/projects/{projectId}更新專案
僅更新傳入的欄位（部分更新）。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
主體參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| 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) |
回應碼
200OK400Bad Request404Not Found
DELETE
/projects/{projectId}刪除專案
刪除專案。成功時回傳 204 No Content（無回應內容）。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
回應碼
204No Content403Forbidden404Not Found
GET
/projects/{projectId}/timeline時間軸（里程碑）
專案里程碑列表 — 名稱、狀態（PLANNED/IN_PROGRESS/COMPLETED）、截止日期、完成日期與進度。依 sortOrder 排序回傳。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
回應碼
200OK403Forbidden404Not Found
GET
/projects/{projectId}/activities活動紀錄
依最新順序回傳專案的任務變更事件 — 類型、訊息、操作者與時間。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
查詢參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| page | integer | 頁碼（從 0 開始，預設 0） |
| size | integer | 每頁數量（預設 50，最大 200） |
回應碼
200OK403Forbidden404Not Found
GET
/projects/{projectId}/files檔案列表
合併回傳專案內任務與留言的附件，依最新排序。fileUrl 為不過期的靜態 URL。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
查詢參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| limit | integer | 最大數量（預設 100，最大 500） |
回應碼
200OK403Forbidden404Not Found
Tasks
GET
/projects/{projectId}/tasks任務列表
回傳專案的任務列表。需要分頁時請使用 /tasks/paged。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
查詢參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| sortBy | string | 排序欄位（預設 createdAt） |
回應碼
200OK403Forbidden404Not Found
POST
/tasks建立任務
建立任務。
主體參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| 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 |
回應碼
201Created400Bad Request401Unauthorized
GET
/tasks/{taskId}查詢任務
查詢單一任務。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| taskIdREQUIRED | integer | 任務 ID |
回應碼
200OK404Not Found
PUT
/tasks/{taskId}更新任務
僅更新傳入的欄位。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| taskIdREQUIRED | integer | 任務 ID |
主體參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| title | string | 標題 |
| status | enum | 狀態 — PENDING·TODO·IN_PROGRESS·IN_REVIEW·BLOCKED·COMPLETED·CANCELLED |
| priority | enum | 優先順序 — URGENT·HIGH·MEDIUM·LOW |
| dueDate | date | 截止日期 — ISO 8601 |
回應碼
200OK400Bad Request404Not Found
DELETE
/tasks/{taskId}刪除任務
刪除任務。成功時回傳 204 No Content。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| taskIdREQUIRED | integer | 任務 ID |
回應碼
204No Content403Forbidden404Not Found
GET
/tasks/assigned我的任務
回傳指派給 API 金鑰帳號的任務列表。
回應碼
200OK401Unauthorized
Documents
GET
/projects/{projectId}/documents文件列表
回傳專案的文件列表。需要分頁時請使用 /documents/paged。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| projectIdREQUIRED | string | 專案 ID — 數字 ID 或以 p_ 開頭的 publicId |
回應碼
200OK403Forbidden404Not Found
GET
/documents/{documentId}查詢文件
查詢單一文件（含內文）。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| documentIdREQUIRED | integer | 文件 ID |
回應碼
200OK404Not Found
POST
/documents建立文件
建立文件。
主體參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| workspaceIdREQUIRED | integer | 工作區 ID |
| titleREQUIRED | string | 標題 |
| documentTypeREQUIRED | enum | 文件類型（如 REQUIREMENT, MEETING_NOTE） |
| projectId | integer | 專案 ID（數字） |
| content | string | 文件內文 |
| visibility | enum | 可見範圍 — PUBLIC·TEAM·PRIVATE |
回應碼
201Created400Bad Request401Unauthorized
PUT
/documents/{documentId}更新文件
僅更新傳入的欄位。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| documentIdREQUIRED | integer | 文件 ID |
主體參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| title | string | 標題 |
| content | string | 文件內文 |
| visibility | enum | 可見範圍 — PUBLIC·TEAM·PRIVATE |
回應碼
200OK400Bad Request404Not Found
DELETE
/documents/{documentId}刪除文件
刪除文件。成功時回傳 204 No Content。
路徑參數
| 名稱 | 型別 | 說明 |
|---|---|---|
| documentIdREQUIRED | integer | 文件 ID |
回應碼
204No Content403Forbidden404Not Found
ERRORS
錯誤碼
每個錯誤回應都包含 error.code 與 error.message。
| 代碼 | 名稱 | 說明 | 處理方式 |
|---|---|---|---|
| 400 | Bad Request | 請求主體無效。 | 驗證請求主體 |
| 401 | Unauthorized | API 金鑰無效或遺漏。 | 重新確認 API 金鑰 |
| 403 | Forbidden | 您沒有存取此資源的權限。 使用唯讀金鑰發送寫入請求時會回傳 SCOPE_FORBIDDEN。 | 檢查角色／範圍 |
| 404 | Not Found | 找不到所請求的資源。 | 重新確認 ID |
| 429 | Rate Limited | 您已超過速率限制。 | 參照 Retry-After 標頭並延後重試 |
| 500 | Server Error | 伺服器處理請求時發生錯誤。 | 5 分鐘後重試，並查看 status.pjt.ai |