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 req/分 + 月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}ワークスペース取得
ワークスペースを1件取得します。
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 | プロジェクトコード（タスクキーのprefix）。省略時は名前から自動生成 |
| 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}タスク取得
タスクを1件取得します。
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}ドキュメント取得
ドキュメントを1件（本文含む）取得します。
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 | このリソースへのアクセス権限がありません。 read 専用キーで書き込みリクエストを行うと SCOPE_FORBIDDEN が返ります。 | ロール/スコープを確認 |
| 404 | Not Found | 要求されたリソースが見つかりません。 | IDを再確認 |
| 429 | Rate Limited | レート制限を超過しました。 | Retry-Afterヘッダーを参照し、バックオフを適用 |
| 500 | Server Error | サーバー処理中にエラーが発生しました。 | 5分後に再試行、status.pjt.aiを確認 |