HTTP 規約

認証が必要な /v1 の業務操作には、Authorization: Bearer <access-token> を使います。AI レビュー API の POST /v1/reviews は専用の API キーを使い、リクエスト・再試行・エラーの仕様も専用ページで説明しています。

主なエンドポイント

AI 評価には GET/POST /v1/cases/:id/report、提案への対応には POST /v1/cases/:id/report/actions を使います。

タスクと記録は案件に、改善提案はプレイブックに紐づきます。案件をまたぐタスク一覧や、プレイブックをまたぐ改善提案の一覧も取得できます。

エイリアスは所有元と名前の組（ownerId、alias）で識別します。個人または管理できるワークスペースごとに、閲覧できるプレイブックへのエイリアスを1つ設定できます。プレイブックの所有者が設定したものは公式の名前として表示し、第三者が設定したものは、その設定者自身の操作でのみ返します。

自分のタスクは assignedTo=me、送信した改善提案は view=sent、管理するプレイブック宛ての改善提案は view=inbox で取得します。改善提案の一覧には認証が必要です。

操作対象とページ分割

管理用の対応エンドポイントでは、クエリパラメーターの workspaceId で操作対象を指定します。その他の機能では、Bearer 認証情報から呼び出し元を確認します。CLI に保存したワークスペース設定が、直接送る HTTP リクエストにも適用されるわけではありません。

一覧では pageSize と cursor を使います。返されたカーソルをそのまま渡し、自分で生成・解読しないでください。記録は作成日時と ID（createdAt、id）を使って安定した順序で返し、order=asc|desc で並び順を指定できます。フィルターで絞り込んでも、現在のアクセス権限で読める範囲は広がりません。

データの変更

変更リクエストには idempotencyKey を指定します。同じキーを再利用するのは、通信の失敗などで応答を確認できず、同じ内容を再送するときだけです。

案件やタスクの変更には expectedLockVersion、プレイブックの公開には baseVersionId を指定します。現在の状態と一致しない場合は競合エラーになるため、最新の状態を取得して変更内容を再検討します。

案件やタスクを終了するときは、新しい記録も同時に送れます。状態の変更と最終成果の記録を、一つの処理として保存できます。

入力の更新とプレイブックの選択

PATCH /v1/cases/{caseId} は任意の title・input・versionId と、必須の expectedLockVersion・idempotencyKey を受け付けます。更新項目を少なくとも 1 つ指定してください。進行中（open）案件では、versionId に閲覧可能かつアーカイブされていないバージョンを指定するとプレイブックを追加・差し替えできます。null を指定すると解除し、省略すると現在の選択を維持します。案件の編集権限が必要で、終了済み案件は先に再開してください。

タイトル・入力・プレイブックの更新では、プレイブックが設定されている場合、保存後の入力が選択したバージョンの入力スキーマを満たすかを検証します。input を渡すとオブジェクト全体を置き換え、省略すると現在値を使います。プレイブックの選択と入力の置き換えはまとめて保存し、検証に失敗したらどちらも保存しません。プレイブックを解除すると入力は維持し、以前のスキーマは適用しません。

{
	"versionId": "<version-uuid>",
	"input": { "customer": "Acme" },
	"expectedLockVersion": 1,
	"idempotencyKey": "<new-uuid>"
}

プレイブックを解除するには、最新のロックバージョンと新しい冪等性キーに加えて "versionId": null を送ります。

プレイブックの追加・差し替え・解除はシステムの履歴に残り、変更前と選択後のバージョンを該当する場合に記録します。既存のタスク・記録・レポートは維持し、タスクは元のステップへの参照を保持します。

エラー

自動で再試行するのは、429 と一時的な 5xx だけにします。待機時間を段階的に延ばし、回数の上限を設けてください。入力・権限・競合のエラーは、そのまま再送しません。競合した場合は、最新の状態を読んでから、人やエージェントが変更内容を判断します。

外部ソース

POST   /v1/cases/{caseId}/sources
POST   /v1/cases/{caseId}/sources/{sourceId}/refresh
DELETE /v1/cases/{caseId}/sources/{sourceId}
GET    /v1/cases/{caseId}/sources/{sourceId}

現在のスペースに接続した本人のアカウントで、Slack スレッド、Discord メッセージ・スレッド、Google Docs・Sheets・Slides のファイルを紐づけます。Slack と Discord はワークスペース専用で、Google Drive は個人スペースとワークスペースの両方に対応します。Google Drive は先に Web で接続し、Google Picker でファイルを選択してください。URL だけではアクセス権は付与されません。Google Drive のプロバイダーキーは gdrive です。紐づけ・解除は各2クレジットで、初回の取得は紐づけ料金に含まれます。手動・自動の再取得は完了時に、そのソースを持つ案件の課金アカウントへ1クレジットを計上します。終了済み案件では明示的な再取得依頼だけを処理します。依頼の受付、失敗、ページ分割、再試行は無料です。複数の依頼を1回の取得にまとめた場合、その案件への課金は1回だけです。case get の sources は案件の作業共有先だけに返されます。閲覧は保存済みの内容を使うため、取得状態と日時を確認してください。内容が省略された場合は、ソース ID で最新の保存内容全体を取得します。過去の内容は保持しません。外部ソースは記録とは別で、公開閲覧者には返しません。共有範囲・自動更新・取得内容の削除については Slack・Discord・Google Drive を参照してください。

紐づけ時のリクエスト本文に必要な項目は url と idempotencyKey、再取得・解除は idempotencyKey です。すべて案件の作業権限が必要で、紐づけには進行中の案件が必要です。ソース取得では sourceId を指定して最新の保存内容を読み、外部サービスにはアクセスしません。記録一覧の種別は note・output・activity・agreement で、source という記録種別はありません。

作成時の明示的な共有設定と共有設定の更新は access: { visibility, grants } を使います。公開範囲は restricted/public、共有先はユーザー・チームの UUID または登録済みユーザーのメールアドレスをキーに viewer/editor を指定します。メールアドレスは保存前にユーザーの UUID に解決し、応答は UUID を返します。未登録のメールアドレスや、同じユーザーに解決される共有先の権限が競合する場合は、更新全体を拒否します。更新は設定全体を置き換えるため、無関係な共有先を保持し、自分への直接共有を残す場合も含めてください。所有者は共有設定とは独立して管理権限を持ち、担当者や管理者には自動で権限を付与しません。編集者は共有設定の取得・変更、少なくとも1件の明示的な編集者を保持した共有設定の変更、アーカイブ・復元ができます。通常の取得結果には非公開の共有先一覧が含まれないため、編集者は共有設定の取得操作で設定全体を確認します。アクセスと権限も参照してください。

公開案件では現在のタイトル、入力、タスク、記録、閲覧可能な引き継ぎを読めます。後から追加した内容も公開対象です。作成者・担当者の公開プロフィールへの参照は含みますが、非公開の共有先、リンク元資料、AI の評価レポート・要約、内部設定は含みません。公開設定では閲覧だけを許可します。明示的に共有された閲覧者は非公開案件とリンク元資料も読めますが、更新には編集権限が必要です。

読める保存済みバージョンをコピーして、独立した内容として調整できます。コピーは独自の内容とバージョンを持ち、共有設定、下書き、案件、提案、エイリアス、スター、履歴を引き継ぎません。編集は同期されません。共有設定を明示してください。ownerId を省略すると選択中のワークスペース、未選択なら個人アカウントを所有元にします。copiedFrom は直近の元プレイブックと固定バージョンを保持し、sourceAccessible は元を現在も読めるかを示します。コピー一覧には読めるものだけを返します。料金は通常のプレイブック作成と同じです。

POST /v1/playbooks/:id/copies は sourceVersionId と idempotencyKey が必須で、任意の ownerId・title と作成時の共有指定（private・teamIds・access のいずれか1つ）を受け取ります。GET /v1/playbooks/:id/copies は pageSize と cursor を受け取ります。

チームには複数のワークスペースを接続できます。チーム招待の送信・一覧表示・取り消しは、接続済みワークスペースのオーナーまたは管理者であるチーム参加者のみが行えます。受信者は招待先のメールでログインして既存のワークスペースを選ぶか新規作成します。送信者は接続先を指定しません。受け入れ時にはワークスペースを接続し受信者を参加者にしますが、所属メンバー全員を追加するわけではありません。すでにチームに接続済みのワークスペースで招待を受け入れると、招待を消費せずに HTTP 409 を返します。そのワークスペースの参加者はチームのメンバー管理から追加してください。各ワークスペースは自分の参加者を管理します。同じユーザーは複数のワークスペースから参加でき、あるワークスペースのメンバーから削除しても、ほかのワークスペースからの参加は維持されます。切断するとその接続と参加者を削除し、ほかの接続は保持します。チーム経由の権限には参加元ワークスペースとリソースの所属先の両方が接続中である必要があります。直接のユーザー共有は切断後も維持されます。招待の有効期限は14日で、再送すると前の招待を閉じます。接続してもワークスペースの購読要件は変わりません。

POST/GET /v1/teams/:teamId/invitations?workspaceId=... (POST: { "emails": ["customer@example.com"] }); DELETE /v1/teams/:teamId/invitations/:invitationId; DELETE /v1/teams/:teamId/connection; GET /v1/invitations/:token; POST /v1/invitations/:token/accept?workspaceId=....

/acl の更新ルートは廃止されました。入れ子の設定を /access に送信してください。チーム招待には認証が必要で、リソース更新の冪等性キーは使いません。ワークスペース作成では任意の teamInvitationToken を指定し、接続と参加を同じトランザクションで完了できます。

所有・責任・ライフサイクル

プレイブックと案件には所有元のユーザーまたはワークスペースのアカウント（ownerId）があり、請求先も兼ねます。個人所有者は全権限を持ち、ワークスペース所有の場合は現在のオーナー・管理者が所有権限を行使します。それ以外のメンバーには、ユーザー・チームへの明示的な共有、または公開コンテンツへの公開設定が必要です。所属だけでリソースへの権限は得られません。退会時には、そのワークスペースが所有するアイテムへの直接共有も、完了・アーカイブ済みを含めて解除されます。解除によって編集者がゼロになるアイテムがあれば、完了・アーカイブ済みも含め、先に別のユーザーまたはチームを編集者に追加してください。個人所有や別ワークスペースのアイテムへの共有は維持されます。チーム経由の権限と管理権限は現在の所属に従います。必須 SSO は所属メンバーに適用し、非メンバーへの直接共有は通常の Epismo 認証で利用できます。ワークスペース間のチーム共有では、参加元ワークスペースの SSO を確認します。一覧は明示的な共有と対応する公開設定で決まり、所有権限だけでは表示されません。

作成・コピー時の ownerId を省略すると、選択中のワークスペース、未選択なら個人アカウントを所有元にします。明示指定にも権限確認が適用されます。保存済みの接続先を含め、ワークスペースを選択している場合、作成時は private: true、空でない teamIds、access のいずれか1つを明示します。個人スペースでは共有指定を省略できます。選択したチームの編集権限で作成者も編集できるため、重複する直接共有は追加しません。明示した作成者への共有は保持します。管理者や担当者の指定は共有設定の代わりにはなりません。

アーカイブは終了とは別の操作です。編集者と所有者は Web・CLI・API・MCP から実行できます。アーカイブ済み案件は通常の一覧・件数・引き継ぎグラフから外れ、開けなくなりますが、作業内容は保持します。archived=true（CLI は case list --archived）で UUID と最新のロックバージョンを取得し、状態・担当・共有設定を変えずに復元できます。完全削除は所有者だけが行え、アーカイブ済み案件の最新の expectedLockVersion が必要です。タスク・記録・資料キャプチャ・引き継ぎリンクを削除しますが、他の案件や外部サービスの原本は変更しません。

提案は現在の親プレイブックに紐づき、独立した所有者や共有範囲のスナップショットを持ちません。authorId は作成者、baseVersionId は改善を検討するための不変の内容参照です。閲覧には親への現在のアクセス権が必要で、親がアーカイブされると復元まで提案も読めません。作成者は親へのアクセス権を保持している間、未解決の自分の提案を編集でき、現在のプレイブック編集者が採用・却下を行えます。移管後も既存の提案は親の現在の共有設定に従います。採用済みにする前に結果のバージョンを保存してください。

POST   /v1/playbooks/{playbookId}/restore
PATCH  /v1/playbooks/{playbookId}/assignee
POST   /v1/cases/{caseId}/archive
POST   /v1/cases/{caseId}/restore
DELETE /v1/cases/{caseId}
POST   /v1/workspaces/{workspaceId}/member-handover

メンバー削除前に、オーナー・管理者は案件担当・プレイブックの管理者・共有権限の引き継ぎをプレビューして実行できます。未完了の承認タスクは明示指定した場合だけ引き継ぎ、完了済み承認と作成者は履歴として保持します。現在の所属メンバーから後任を選び、プレビューを確認してください。workspace member handover <workspace-id> --member-id <user-id> --successor-id <user-id> は既定でプレビューです。--preview=false で実行すると後任へ編集権限を明示的に付与します。次に workspace member delete --workspace-id <workspace-id> <user-id> で所属を削除し、--preview=false --finalize で引き継ぎを再実行して、その間の変更も整理します。引き継ぎの最終処理（finalize）は所属の削除後にだけ実行でき、メンバー削除そのものは行いません。退会により該当するチーム経由の権限とワークスペース管理権限は失われます。最初の引き継ぎでは直接共有を保持し、所属削除時にそのワークスペース所有のアイテムへの共有を解除します。最終処理でも、途中で追加された共有を整理します。個人所有や別ワークスペースへの共有は維持されます。

HTTP の引き継ぎリクエストは memberId、successorId、transferApprovals を使います。レスポンスには cases、playbooks、tasks、approvals、suggestions の件数を返します。この仕様で CLI の引き継ぎコマンドを使うには、対応する CLI リリースが必要です。

案件の所有元移管には epismo_case_owner_transfer、case owner transfer <case-id> --owner-id <account-id> --lock-version <n>、または PATCH /v1/cases/{caseId}/owner（ownerId・expectedLockVersion・idempotencyKey）を使います。現在の所有権限が必要です。個人所有の案件は接続中のワークスペースへ移せますが、公開案件には移管先の管理権限も必要です。ワークスペース所有の案件は、作成者またはそのワークスペースのオーナーへ移せます。個人間・ワークスペース間の移管はできません。担当と共有設定を維持し、請求先を変更して、生成された評価レポートを消去します。担当変更だけではこれらの所有元に関する変更は行いません。

プレイブックの担当変更も案件と同じ assignedTo を使い、応答でも assignedTo として返します。epismo_playbook_assign、playbook assign <playbook-id> --assigned-to <user-id>、または PATCH /v1/playbooks/{playbookId}/assignee を使います。変更には所有権限、選ぶ相手には既存の編集権限が必要です。

保存済みの評価を読む

GET /v1/cases/{caseId} は閲覧可能な最新の report と reportJob を含み、履歴の取得や AI の実行は行いません。GET /v1/cases/{caseId}/report/history は新しい順の要約 reports と、続きがある場合の nextCursor を返します。pageSize（既定 20、最大 100）と cursor でページ分割できます。GET /v1/cases/{caseId}/report?reportId=REPORT_ID で選択した評価の全体を読み、reportId を省略すると最新レポートと生成ジョブを取得します。

履歴の閲覧には現在の案件の作業権限が必要で、現在の共有範囲と一致する評価だけが返ります。公開閲覧者にはレポートも要約も返しません。新しい評価に置き換わったレポートは historical: true の読み取り専用となり、未処理の提案を採用・対応不要にすると HTTP 409 を返します。最新のレポートを読み、提案内容を確認し直してから操作してください。証拠が変わっただけの場合は、引き続き再評価を勧める通知にとどまります。

個人・チームレポート

個人レポートは現在の請求元の範囲で生成した本人だけが読めます。チームレポートと提案への対応結果は、現在のワークスペースを通じたチームの参加者で共有します。 対象の選び方、作業の健全性、履歴、共有の扱いは AI レビューを参照してください。

生成には UUID の idempotencyKey を指定し、HTTP 202 とジョブを受け取ります。閲覧は ReportResponse（report、任意の job、historical）を返します。jobId または reportId のどちらかを指定し、両方を同時には使いません。履歴は pageSize・cursor に対応します。提案への対応では proposalId・action（create または dismiss）と任意の対応不要の理由 feedback を指定します。保存済み内容を変更せず使い、idempotencyKey は指定しません。チーム ID はパスから、ワークスペースと請求元の権限は認証から決まります。