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キーはサーバー側でのみ使用してください。クライアント（ブラウザ・モバイルアプリ）に露出した場合は、直ちにキーを失効・再発行してください。

🔑

キーの権限

API キーは発行したアカウントの権限で動作します。既存テナント（tenantId）配下での作成は、そのアカウントがテナントの OWNER/ADMIN である必要があります（でなければ 403）。新規テナント作成時は、そのアカウントが OWNER になります。provisioning スコープのキー発行は SUPER_ADMIN のみ可能です。

Account

GET/me

自分の API キー情報（接続テスト）

API キーの有効性と能力（スコープ）を返します。GET なので write スコープは不要 — read-only キーでも自分の能力を確認できます。キーが無い・無効・失効なら 401 を返し、それ自体が接続テスト結果です。応答の canProvision/canWrite/canRead で可否を事前判定してください（例: canProvision=false ならプロビジョニング呼び出し前に「このキーでは不可」と警告 → 誤った緑表示を防止）。インフラの liveness（サーバ生存確認）とは別物です。

Response codes

200OK401Unauthorized

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

401UNAUTHORIZEDX-API-Key の欠落・無効・失効 — この 401 自体が「未接続」の信号です（200 なら接続正常）。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Provisioning

POST/provisioning/workspacesEnterprise 専用

ワークスペースのプロビジョニング（冪等）

provisioning スコープの API キーで、テナントとワークスペースを一度に用意します。tenantId を送るとそのテナント（呼び出しキーのアカウントが OWNER/ADMIN）を使用し、無い場合は tenantExternalRef でアカウント名前空間内に冪等に検索/作成します（両方無いと 400）。workspaceExternalRef は必須の冪等キー — 再リクエスト時は新規作成（201）ではなく既存リソースを 200 で返し、createdTenant/createdWorkspace で区別します。スコープ階層 provisioning ⊃ write（別途 write 不要）。⚠️ businessType は現状結果に影響なし（audit のみ）、defaultLocale/accentHue/template は緩い検証（正確な許可値を送信・不明な template は無視）、応答の tenant.myRole は null の場合があり権限判断に使わないこと。

このエンドポイントは Enterprise プランでのみ利用できます。プロビジョニングスコープのキー発行・利用は Enterprise 契約に含まれます。

Body parameters

名前	型	説明
tenantId	integer	既存テナント ID（Long, optional）。指定時は tenant·tenantExternalRef を無視。呼び出しキーのアカウントがそのテナントの OWNER/ADMIN である必要があります
tenantExternalRef	string	新規テナントの冪等キー（≤100, tenantId が無いとき）。同じ（アカウント, 値）で既存テナントを再利用
tenant.name	string	新規テナント名（≤100, 省略時は workspace.name を使用）
tenant.slug	string	新規テナント slug（≤50, グローバル一意・未指定時は自動生成）
tenant.description	string	新規テナント説明（≤500）
workspaceExternalRefREQUIRED	string	ワークスペースの冪等キー（≤100, 必須）。同じ（tenantId, 値）で既存ワークスペースを再利用
workspace.nameREQUIRED	string	ワークスペース名（≤100, 必須）
workspace.slug	string	ワークスペース slug（≤50, テナント内で一意・未指定時は name から派生）
workspace.description	string	ワークスペース説明（≤500）
workspace.defaultLocale	string	既定ロケール — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th（未検証・正確な値を送信）
workspace.accentHue	integer	アクセント色相（0〜360, 未検証）
workspace.template	string	プリセット — BLANK\|DEV\|AGENCY\|OPS（不明な値は無視）
workspace.businessType	string	業種（forward-looking）— audit のみ・作成ワークスペースには未反映

Response codes

200OK201Created400Bad Request401Unauthorized403Forbidden429Rate Limited

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403SCOPE_FORBIDDENread-only キー（write スコープなし）で書き込みを試行 — ゲートウェイのフィルタが遮断

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDENprovisioning スコープのないキー — このエンドポイントは provisioning が必須（write だけでは不可）

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "The 'provisioning' scope is required."
}

403FORBIDDEN既存 tenantId 指定時、呼び出しアカウントがそのテナントの OWNER/ADMIN でない（またはメンバーでない）

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "OWNER or ADMIN role on the tenant is required."
}

400BAD_REQUESTtenantId・tenantExternalRef のどちらも送っていない

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "One of tenantId or tenantExternalRef is required."
}

400VALIDATION_ERROR必須/長さ等の検証失敗 — errors[] にフィールドごとの詳細

{
  "timestamp": "2026-07-14T09:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "workspaceExternalRef: must not be blank",
  "errors": [
    { "field": "workspaceExternalRef", "code": "NotBlank", "message": "must not be blank" }
  ]
}

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Tenants

GET/tenants

自分のテナント一覧

API キーのアカウントが所属する全テナントを返します（テナント直接メンバー + ワークスペース経由でのみ到達する組織=MEMBER）。GET なので read スコープで十分です。各項目の myRole（OWNER|ADMIN|MEMBER）で権限を判定してください — ワークスペース作成（POST /workspaces）は myRole ∈ [OWNER, ADMIN] のテナントでのみ可能なので、SI クライアントはこの一覧から OWNER/ADMIN の項目の id を選び tenantId として使用します。

Response fields

名前	型	説明
id	Long	POST /workspaces の tenantId として使用するテナントID
myRole	String (enum)	OWNER \| ADMIN \| MEMBER（未所属は null）。ワークスペース作成（POST /workspaces）は OWNER/ADMIN のテナントでのみ可能
status	String (enum)	テナント状態 — ACTIVE \| ARCHIVED \| DELETE（Tenant.Status）
slug	String	組織スラッグ（ルーティング用）
mfaSetupRequired	boolean	組織が2FAを強制し、未設定の場合は true
slugSet	boolean	ユーザーがスラッグを直接設定したか（自動生成の org-xxxx は false）

Response codes

200OK401Unauthorized

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/tenants/{tenantId}

テナント単件

テナント 1 件を一覧と同じ shape で返します。所属していなければアクセス検証失敗（403）、存在しないテナントなら 400 tenant.not_found。read スコープで十分です。

Path parameters

名前	型	説明
tenantIdREQUIRED	integer	取得するテナント ID（Long, 必須）

Response codes

200OK400Bad Request401Unauthorized403Forbidden

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403FORBIDDEN呼び出しアカウントがそのテナントのメンバーでない（tenant アクセス検証失敗）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400BAD_REQUEST存在しないテナント（tenant.not_found）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트를 찾을 수 없습니다"
}

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Workspaces

POST/workspaces

ワークスペース作成（既存テナント）

プロビジョニングとは別の軽量経路 — テナントは作成せず、既存テナント（tenantId）配下にワークスペースだけを作成します。write スコープで十分（provisioning 不要・read-only キーは 403 SCOPE_FORBIDDEN）。呼び出しキーのアカウントがそのテナントの OWNER/ADMIN である必要があります。externalRef を渡すと冪等 — 同じ（tenantId, externalRef）で再リクエストすると新規作成（201）ではなく既存ワークスペースを 200 で返します。省略すると呼び出しごとに新規作成されます（再試行安全のため付与推奨）。作成物はチームワークスペース（個人ではない）です。⚠️ defaultLocale/accentHue/template は緩い検証（値はそのまま通過・不明な template は無視）。テナントの自動作成が必要な場合はプロビジョニング（POST /provisioning/workspaces）を使用してください。

Body parameters

名前	型	説明
tenantIdREQUIRED	integer	このテナント配下に作成（Long, 必須）。呼び出しキーのアカウントがそのテナントの OWNER/ADMIN である必要があります
externalRef	string	冪等キー（≤100, optional）。同じ（tenantId, 値）で再リクエストすると既存ワークスペースを返す。省略時は呼び出しごとに新規作成
nameREQUIRED	string	ワークスペース名（≤100, 必須）
slug	string	ワークスペース slug（≤50, テナント内で一意・未指定時は name から派生）
description	string	ワークスペース説明（≤500）
defaultLocale	string	既定ロケール — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th（未検証で通過・正確な値を送信）
accentHue	integer	アクセント色相（0〜360, 未検証で通過）
template	string	プリセット — BLANK\|DEV\|AGENCY\|OPS（不明な値は静かに無視）

Response codes

201Created200OK400Bad Request401Unauthorized403Forbidden

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403SCOPE_FORBIDDENread-only キー（write スコープなし）で書き込みを試行 — ゲートウェイのフィルタが遮断

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDEN呼び出しアカウントが tenantId テナントの OWNER/ADMIN でない（tenant.admin_required）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

403FORBIDDEN呼び出しアカウントがそのテナントのメンバーでない（存在しないテナントを含む、tenant.not_member）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400VALIDATION_ERROR必須/長さ等の検証失敗（tenantId・name の欠落など）— errors[] にフィールドごとの詳細

{
  "timestamp": "2026-07-14T20:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "tenantId: must not be null",
  "errors": [
    { "field": "tenantId", "code": "NotNull", "message": "must not be null" }
  ]
}

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces/slug/available

ワークスペース slug の重複確認

テナント内でワークスペース slug が利用可能か(重複していないか)を検査します。slug は (tenantId, slug) で一意なため、ワークスペース作成と同様に tenantId が必要です。slug は保存ルールと同じく正規化(前後の空白除去・小文字化)してから比較し、空値・重複の場合は available:false になります。認可はワークスペース作成と同じゲート — 呼び出しアカウントは該当テナントの OWNER/ADMIN でなければならず(requireTenantAdmin)、非メンバー・非管理者は 403 で、テナントの存在有無は開示しません。GET なので read スコープで十分です。ワークスペース作成(POST /workspaces)の前に、この API で slug の利用可否を事前確認してください。

Query parameters

名前	型	説明
tenantIdREQUIRED	integer	このテナント範囲で重複検査(Long、必須 query)。slug の一意スコープ。呼び出しアカウントはこのテナントの OWNER/ADMIN である必要あり
slugREQUIRED	string	確認するワークスペース slug(query、必須)。正規化(trim・小文字)後に比較

Response fields

名前	型	説明
available	boolean	true=利用可能(重複なし)、false=既に使用中または空の slug

Response codes

200OK401Unauthorized403Forbidden

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403FORBIDDEN呼び出しアカウントが tenantId テナントの OWNER/ADMIN ではない(非メンバー含む) — requireTenantAdmin で遮断(テナント存在は非開示)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

401UNAUTHORIZEDX-API-Key の欠落・無効・期限切れ(External 共通)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces

ワークスペース一覧

APIキーのアカウントがアクセスできるワークスペース一覧を返します。

Response codes

200OK401Unauthorized429Rate Limited

GET/workspaces/{workspaceId}

ワークスペース取得

ワークスペースを1件取得します。

Path parameters

名前	型	説明
workspaceIdREQUIRED	integer	ワークスペースID

Response codes

200OK401Unauthorized404Not Found

Projects

GET/projects

プロジェクト一覧（テナント・WS指定）

指定したテナント・ワークスペースのプロジェクト一覧をページ単位で返します。tenantId と workspaceId は必須で、status で追加フィルタできます。

Query parameters

名前	型	説明
tenantIdREQUIRED	integer	テナントID（必須）
workspaceIdREQUIRED	integer	ワークスペースID（必須）
status	enum	プロジェクト状態の完全一致（PLANNING・ESTIMATING・WAITING・IN_PROGRESS・ON_HOLD・COMPLETED・CANCELLED）。指定時はキャンセル・アーカイブも含む。
page	integer	ページ番号（0から）
size	integer	ページサイズ（デフォルト20、上限100）

Response codes

200OK400Bad Request401Unauthorized403Forbidden429Rate Limited

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

400BAD_REQUESTワークスペースが存在しない、またはそのテナントに属さない（クロステナントは存在を明かさず not_found）。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스를 찾을 수 없습니다"
}

400BAD_REQUESTstatus に許可されない値が渡された。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "유효하지 않은 프로젝트 상태 값입니다"
}

403FORBIDDENこのワークスペースへのアクセス権がない（ACTIVEメンバーまたは承認済みクライアント/パートナーでない — テナントメンバーシップのフォールバックなし）。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스 접근 권한이 없습니다"
}

401UNAUTHORIZEDX-API-Key の欠落・無効・期限切れ。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

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を確認

OVERVIEW

PJT AI REST API

基本事項

認証 — 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キーから（発行時に一度だけ表示）。

⚠

キーの保管

🔑

キーの権限

Account

GET/me

自分の API キー情報（接続テスト）

Response codes

200OK401Unauthorized

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

401UNAUTHORIZEDX-API-Key の欠落・無効・失効 — この 401 自体が「未接続」の信号です（200 なら接続正常）。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Provisioning

POST/provisioning/workspacesEnterprise 専用

ワークスペースのプロビジョニング（冪等）

このエンドポイントは Enterprise プランでのみ利用できます。プロビジョニングスコープのキー発行・利用は Enterprise 契約に含まれます。

Body parameters

名前	型	説明
tenantId	integer	既存テナント ID（Long, optional）。指定時は tenant·tenantExternalRef を無視。呼び出しキーのアカウントがそのテナントの OWNER/ADMIN である必要があります
tenantExternalRef	string	新規テナントの冪等キー（≤100, tenantId が無いとき）。同じ（アカウント, 値）で既存テナントを再利用
tenant.name	string	新規テナント名（≤100, 省略時は workspace.name を使用）
tenant.slug	string	新規テナント slug（≤50, グローバル一意・未指定時は自動生成）
tenant.description	string	新規テナント説明（≤500）
workspaceExternalRefREQUIRED	string	ワークスペースの冪等キー（≤100, 必須）。同じ（tenantId, 値）で既存ワークスペースを再利用
workspace.nameREQUIRED	string	ワークスペース名（≤100, 必須）
workspace.slug	string	ワークスペース slug（≤50, テナント内で一意・未指定時は name から派生）
workspace.description	string	ワークスペース説明（≤500）
workspace.defaultLocale	string	既定ロケール — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th（未検証・正確な値を送信）
workspace.accentHue	integer	アクセント色相（0〜360, 未検証）
workspace.template	string	プリセット — BLANK\|DEV\|AGENCY\|OPS（不明な値は無視）
workspace.businessType	string	業種（forward-looking）— audit のみ・作成ワークスペースには未反映

Response codes

200OK201Created400Bad Request401Unauthorized403Forbidden429Rate Limited

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403SCOPE_FORBIDDENread-only キー（write スコープなし）で書き込みを試行 — ゲートウェイのフィルタが遮断

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDENprovisioning スコープのないキー — このエンドポイントは provisioning が必須（write だけでは不可）

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "The 'provisioning' scope is required."
}

403FORBIDDEN既存 tenantId 指定時、呼び出しアカウントがそのテナントの OWNER/ADMIN でない（またはメンバーでない）

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "OWNER or ADMIN role on the tenant is required."
}

400BAD_REQUESTtenantId・tenantExternalRef のどちらも送っていない

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "One of tenantId or tenantExternalRef is required."
}

400VALIDATION_ERROR必須/長さ等の検証失敗 — errors[] にフィールドごとの詳細

{
  "timestamp": "2026-07-14T09:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "workspaceExternalRef: must not be blank",
  "errors": [
    { "field": "workspaceExternalRef", "code": "NotBlank", "message": "must not be blank" }
  ]
}

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Tenants

GET/tenants

自分のテナント一覧

Response fields

名前	型	説明
id	Long	POST /workspaces の tenantId として使用するテナントID
myRole	String (enum)	OWNER \| ADMIN \| MEMBER（未所属は null）。ワークスペース作成（POST /workspaces）は OWNER/ADMIN のテナントでのみ可能
status	String (enum)	テナント状態 — ACTIVE \| ARCHIVED \| DELETE（Tenant.Status）
slug	String	組織スラッグ（ルーティング用）
mfaSetupRequired	boolean	組織が2FAを強制し、未設定の場合は true
slugSet	boolean	ユーザーがスラッグを直接設定したか（自動生成の org-xxxx は false）

Response codes

200OK401Unauthorized

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/tenants/{tenantId}

テナント単件

Path parameters

名前	型	説明
tenantIdREQUIRED	integer	取得するテナント ID（Long, 必須）

Response codes

200OK400Bad Request401Unauthorized403Forbidden

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403FORBIDDEN呼び出しアカウントがそのテナントのメンバーでない（tenant アクセス検証失敗）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400BAD_REQUEST存在しないテナント（tenant.not_found）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트를 찾을 수 없습니다"
}

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

Workspaces

POST/workspaces

ワークスペース作成（既存テナント）

Body parameters

名前	型	説明
tenantIdREQUIRED	integer	このテナント配下に作成（Long, 必須）。呼び出しキーのアカウントがそのテナントの OWNER/ADMIN である必要があります
externalRef	string	冪等キー（≤100, optional）。同じ（tenantId, 値）で再リクエストすると既存ワークスペースを返す。省略時は呼び出しごとに新規作成
nameREQUIRED	string	ワークスペース名（≤100, 必須）
slug	string	ワークスペース slug（≤50, テナント内で一意・未指定時は name から派生）
description	string	ワークスペース説明（≤500）
defaultLocale	string	既定ロケール — ko\|en\|ja\|zh\|zh-TW\|es\|vi\|th（未検証で通過・正確な値を送信）
accentHue	integer	アクセント色相（0〜360, 未検証で通過）
template	string	プリセット — BLANK\|DEV\|AGENCY\|OPS（不明な値は静かに無視）

Response codes

201Created200OK400Bad Request401Unauthorized403Forbidden

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403SCOPE_FORBIDDENread-only キー（write スコープなし）で書き込みを試行 — ゲートウェイのフィルタが遮断

{
  "error": "SCOPE_FORBIDDEN",
  "message": "This API key is read-only. A 'write' scope is required for this operation."
}

403FORBIDDEN呼び出しアカウントが tenantId テナントの OWNER/ADMIN でない（tenant.admin_required）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

403FORBIDDEN呼び出しアカウントがそのテナントのメンバーでない（存在しないテナントを含む、tenant.not_member）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "테넌트 멤버가 아닙니다"
}

400VALIDATION_ERROR必須/長さ等の検証失敗（tenantId・name の欠落など）— errors[] にフィールドごとの詳細

{
  "timestamp": "2026-07-14T20:00:00Z",
  "code": "VALIDATION_ERROR",
  "message": "tenantId: must not be null",
  "errors": [
    { "field": "tenantId", "code": "NotNull", "message": "must not be null" }
  ]
}

401UNAUTHORIZEDX-API-Key の欠落・無効・失効（External 共通）

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces/slug/available

ワークスペース slug の重複確認

Query parameters

名前	型	説明
tenantIdREQUIRED	integer	このテナント範囲で重複検査(Long、必須 query)。slug の一意スコープ。呼び出しアカウントはこのテナントの OWNER/ADMIN である必要あり
slugREQUIRED	string	確認するワークスペース slug(query、必須)。正規化(trim・小文字)後に比較

Response fields

名前	型	説明
available	boolean	true=利用可能(重複なし)、false=既に使用中または空の slug

Response codes

200OK401Unauthorized403Forbidden

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

403FORBIDDEN呼び出しアカウントが tenantId テナントの OWNER/ADMIN ではない(非メンバー含む) — requireTenantAdmin で遮断(テナント存在は非開示)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "관리자 권한이 필요합니다"
}

401UNAUTHORIZEDX-API-Key の欠落・無効・期限切れ(External 共通)

{
  "timestamp": "2026-07-14T20:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces

ワークスペース一覧

APIキーのアカウントがアクセスできるワークスペース一覧を返します。

Response codes

200OK401Unauthorized429Rate Limited

GET/workspaces/{workspaceId}

ワークスペース取得

ワークスペースを1件取得します。

Path parameters

名前	型	説明
workspaceIdREQUIRED	integer	ワークスペースID

Response codes

200OK401Unauthorized404Not Found

Projects

GET/projects

プロジェクト一覧（テナント・WS指定）

指定したテナント・ワークスペースのプロジェクト一覧をページ単位で返します。tenantId と workspaceId は必須で、status で追加フィルタできます。

Query parameters

名前	型	説明
tenantIdREQUIRED	integer	テナントID（必須）
workspaceIdREQUIRED	integer	ワークスペースID（必須）
status	enum	プロジェクト状態の完全一致（PLANNING・ESTIMATING・WAITING・IN_PROGRESS・ON_HOLD・COMPLETED・CANCELLED）。指定時はキャンセル・アーカイブも含む。
page	integer	ページ番号（0から）
size	integer	ページサイズ（デフォルト20、上限100）

Response codes

200OK400Bad Request401Unauthorized403Forbidden429Rate Limited

エラー応答

message フィールドはリクエストのロケール（?lang または Accept-Language）に応じて8ロケールで返されます。

400BAD_REQUESTワークスペースが存在しない、またはそのテナントに属さない（クロステナントは存在を明かさず not_found）。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스를 찾을 수 없습니다"
}

400BAD_REQUESTstatus に許可されない値が渡された。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "유효하지 않은 프로젝트 상태 값입니다"
}

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "워크스페이스 접근 권한이 없습니다"
}

401UNAUTHORIZEDX-API-Key の欠落・無効・期限切れ。

{
  "timestamp": "2026-07-14T09:00:00Z",
  "message": "API key is missing, invalid, or expired."
}

GET/workspaces/{workspaceId}/projects

プロジェクト一覧

ワークスペースのアクティブなプロジェクト一覧を返します（キャンセル・アーカイブ除く）。

Path parameters

名前	型	説明
workspaceIdREQUIRED	integer	ワークスペースID

Response codes

200OK401Unauthorized403Forbidden

POST/projects

プロジェクト作成（冪等）

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を確認