オープン API

PryFox AI オープン API を使うと、外部システムがプロジェクトアクセスキーでタスクを作成し、タスクやログを照会し、リアルタイムのタスクイベントを購読し、プラン確認モードのタスクを承認 / 拒否し、ワークスペースを管理できます。タスクはワークスペース単位で隔離され、同じワークスペース内の複数回の呼び出しは同一のエージェントインスタンス・記憶・会話履歴を共有します。

基本情報

ベース URL：https://pryfox.ai/openapi（オープン API はトップレベルの /openapi 名前空間で、内部 API の /api プレフィックスとは独立）
すべてのインターフェースは統一されたレスポンス形式を返します：{ code, message, data }
- code === 0 は成功、それ以外はエラー
- message は結果の説明
- data は業務データ

認証方式

オープン API はプロジェクトアクセスキーを使用して JWT トークンと交換し、その後のリクエストは Bearer トークンで呼び出します。

1. トークン取得

http

POST /openapi/auth/project-key
Content-Type: application/json

{
  "key": "proj_<uuid>_<random>",
  "projectUuid": "検証用のプロジェクト UUID（任意）"
}

成功レスポンス：

json

{
  "code": 0,
  "message": "认证成功",
  "data": {
    "token": "eyJhbG...",
    "csrfToken": "a49e9e4b88a34ce0b2d63bfb53a885ad",
    "project": { "uuid": "...", "name": "..." },
    "permissions": { "tasks": ["read", "write"] }
  }
}

レスポンスは Set-Cookie ヘッダーで project_token と csrfToken クッキーも設定します。クッキージャーを持たない純粋なバックエンド呼び出し元は、ボディの token を Authorization: Bearer に、csrfToken を X-CSRF-Token ヘッダーにそのまま使用できます。

2. インターフェース呼び出し

シナリオ	必要条件
読み取り API（GET）	`Authorization: Bearer {token}`
書き込み API（POST/PUT/DELETE）	`Authorization: Bearer {token}` + `X-CSRF-Token: {csrfToken}`
SSE ストリーミング	`Authorization: Bearer {token}`、または URL に `?token={token}` を付与（EventSource はカスタムヘッダーを設定できないため）

プロジェクトキーの権限フィールド permissions.tasks には以下が含まれます：

read：タスク、ログ、プラン、ストリーム、ワークスペースの照会
write：タスク作成、ワークスペース管理、プランの承認 / 拒否

プランの承認 / 拒否は tasks:write のみ必要で、独立した approve 権限はありません。

ワークスペースとチャンネル

ワークスペースはオープン API の中核的な隔離単位です。 すべてのタスクはワークスペースに属し、タスク作成時に呼び出し元が workspace_id（UUID）で指定します。

task_id：照会 / ストリーミング / プラン確認に使用する公開タスク ID
workspace_id：呼び出し元が保持するワークスペース UUID、タスクのランタイム帰属を決定
external_user_id：Claw ランタイム内部で使用されるユーザーキー — workspace_id と等価。同じワークスペース内のすべてのタスクは同一のエージェントインスタンス・記憶庫・連続する会話履歴を共有し、同じ workspace_id で 2 回目の呼び出しを行うと 1 回目の文脈を再呼び出しします。異なるワークスペース間でデータが相互に見えることはありません。

チャンネルはワークスペース内でタスクを配送する先を決めます。オープン API は二つの論理チャンネルを公開します：

論理チャンネル	意味	完全チャンネル（サーバー組み立て）	配送
`work-group`	ワークスペース群聊	`workspace:{workspace_id}`	コーディネーターがエージェントを自動選択
`agent:{agent_id}`	エージェントとの私聊	`agent:{agent_id}:ws:{workspace_id}`	手動でそのエージェントを指定

呼び出し元は論理チャンネルを渡し、サーバーは web UI と同じ符号化で完全チャンネルに組み立てます——これによりオープン API のタスクはそのワークスペースの web UI と同じチャンネルに表示されます。組み立て済みの完全チャンネルを渡さないでください。また :ws:{workspace_id} 接尾辞も自带しないでください——サーバーが workspace_id から自動で追加します。

ワークスペースは永続エンティティです：

初回タスク配信時に暗黙的に作成されます（name は空、フロントエンドのリストは短縮 UUID にフォールバック）。ワークスペース管理 API で明示的に作成・命名することもできます。
論理削除後、同じ workspace_id で再度タスクを配信すると、自動的に active に復活します。したがって第三者にとって「削除」は実質的に「一時停止」であり、保持している ID がデッドロックすることはありません。
プロジェクト内のすべての権限ある身元が同じワークスペースを閲覧・干渉できます。

インターフェース一覧

タスク作成

http

POST /openapi/projects/{project_id}/tasks

タスクを配信します。タスクは呼び出し元が指定した workspace_id に帰属し、呼び出し元が同時に指定する論理チャンネルでルーティングされます。

リクエスト本文：

フィールド	型	必須	説明
`content`	string	はい	タスク内容
`workspace_id`	string (UUID)	はい	ワークスペース ID。ランタイム帰属を決定（同 ID でエージェントインスタンス/記憶/履歴を共有）
`channel`	string	はい	論理チャンネル：`work-group`（ワークスペース群聊）または `agent:{agent_id}`（エージェントとの私聊）。サーバーがこれ + `workspace_id` から完全チャンネルを組み立てます。
`mode`	string	いいえ	三状態：`plan`（プラン確認モードを強制）/ `auto`（自動実行を強制）/ 省略（ワークスペース→プロジェクト級のデフォルトにフォールバック、下記参照）。
`metadata`	object	いいえ	メッセージと一緒に保存されるカスタムメタデータ
`reply_to`	string	いいえ	`work-group` チャンネルでのみ有効。返信対象のメッセージ ID

プランモード解決の優先順位（mode 省略時、本タスクの force_plan_mode は以下のフォールバックで算出されます）：

明示 mode='plan' → true；mode='auto' → false
ワークスペースデフォルト workspaces.settings.plan_mode_enabled（プロジェクトメンバーが web UI のワークスペース管理ページで設定）
プロジェクト級デフォルト projects.settings.plan_mode_enabled（ワークスペース未設定時のフォールバック）
兜底 false

オープン API のワークスペース管理 API は plan_mode_enabled を公開しません——ワークスペース級のプランモードデフォルトはプロジェクトメンバーが web UI で設定します。第三者がタスクごとにプランモードを制御するには、タスク作成呼び出しの mode フィールドに plan または auto を渡してください。

レスポンス：

json

{
  "code": 0,
  "message": "任务已派发",
  "data": {
    "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "status": "pending",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "logical_channel": "work-group",
    "agent_id": null,
    "mode": "plan",
    "plan_mode_enabled": true,
    "message_db_id": "0c6e0d89-dc03-4750-bdc3-2745f8cf966e",
    "created_at": "2026-07-07T11:32:58.416Z"
  }
}

channel：組み立てられた完全チャンネル（work-group → workspace:{workspace_id}；agent:{agent_id} → agent:{agent_id}:ws:{workspace_id}）。
logical_channel：呼び出し元が渡した論理チャンネル（work-group / agent:{agent_id}）。
agent_id：work-group 群聊では null（コーディネーターが自動選択）；agent:{agent_id} 私聊ではそのエージェント ID。
mode：呼び出し元が渡した論理値をそのまま返します（plan/auto、省略時は auto として保存）。
plan_mode_enabled：本タスクの実際の効力値（明示 > ワークスペースデフォルト > プロジェクト級フォールバック）で、呼び出し元は後続のプラン確認が必要か否かを判断できます。
workspace_id が存在しない場合、ワークスペース行が暗黙的に作成されます。以前に論理削除されていた場合は、自動的に active に復活します。

タスク一覧

http

GET /openapi/projects/{project_id}/tasks?workspace_id={uuid}&status=running&page=1&limit=20

ワークスペース / 状態で絞り込み、ページネーションでタスク一覧を取得します。page/limit ページネーションまたは before カーソルページネーションをサポートします。

クエリパラメータ：

パラメータ	型	説明
`workspace_id`	string (UUID)	任意。指定するとそのワークスペース下のタスクのみ一覧表示
`status`	string	任意：`pending` / `running` / `planning` / `completed` / `failed` / `cancelled`
`page`	number	ページ番号。デフォルト 1（`before` と排他、`before` 指定時は無視）
`limit`	number	1 ページあたりの件数。デフォルト 20、最大 100
`before`	string (ISO タイムスタンプ)	任意。カーソルページネーション、`created_at < before` のタスクを返却

レスポンス：

json

{
  "code": 0,
  "message": "获取任务列表成功",
  "data": {
    "tasks": [
      {
        "task_id": "42987a4f-...",
        "workspace_id": "8e6bc849-...",
        "channel": "workspace:8e6bc849-...",
        "agent_id": null,
        "mode": "plan",
        "status": "completed",
        "content": "...",
        "plan_id": "492c1f7a-...",
        "started_at": "2026-07-07T03:33:01.528Z",
        "completed_at": "2026-07-07T03:33:01.575Z",
        "result_summary": "...",
        "metadata": {},
        "created_at": "2026-07-07T11:32:58.416Z",
        "updated_at": "2026-07-07T11:33:01.575Z"
      }
    ],
    "has_more": false,
    "next_before": null,
    "page": 1,
    "limit": 20
  }
}

キー帰属：一覧は現在のキーで作成されたタスクのみ返却します。next_before はカーソルで、次回リクエストで before に渡してより古いページを取得します。null は最古まで到達したことを示します。

タスク状態取得

http

GET /openapi/projects/{project_id}/tasks/{task_id}

レスポンス：

json

{
  "code": 0,
  "message": "获取任务状态成功",
  "data": {
    "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "status": "completed",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "mode": "plan",
    "content": "Full lifecycle test",
    "agent_id": null,
    "plan_id": "492c1f7a-f20c-4c56-8293-c384b1530a44",
    "started_at": "2026-07-07T03:33:01.528Z",
    "completed_at": "2026-07-07T03:33:01.575Z",
    "result_summary": "...",
    "metadata": {},
    "created_at": "2026-07-07T11:32:58.416Z",
    "updated_at": "2026-07-07T11:33:01.575Z",
    "active_run": null
  }
}

状態遷移：pending → planning / running → completed | failed | cancelled。

active_run：ベストエフォート。タスクに進行中の実行がある場合 { agent_id, tool_name, started_at, updated_at } を返し、それ以外は null。
キー帰属：現在のキーで作成されたタスクのみ読み取り可能。それ以外は 403「任务不属于当前密钥」。

チャンネルログ取得

http

GET /openapi/projects/{project_id}/channels/logs?channel=work-group&workspace_id={uuid}&limit=50&before=2026-07-07T11:33:00Z

チャンネル級ログ：論理チャンネル + workspace_id の二重パラメータを渡すと、サーバーが完全チャンネルに組み合わせて該当ワークスペースの該当チャンネルの対話ログを照会します——一つのチャンネル下の全タスクのイベントが連続する対話フローとして集約され、task_id ごとに照会する必要はなく、Web UI の同チャンネルログビューと一致します。

論理チャンネル（work-group または agent:{agent_id}）を渡してください。組み合わせ済みの完全チャンネルではありません。:ws:<workspace_id> 接尾辞は自带しないでください——サーバーが workspace_id から自動で追加します。

チャンネルディスパッチ（Web UI の二つのログ照会モードを鏡像）：

work-group：ワークスペース群聊。該当ワークスペースの agent_logs（message/tool_call/tool_response/progress/error/llm_request/llm_response）とユーザー質問（work_group_messages の sender_type='user'）を集約。
agent:{agent_id}：ワークスペース内の特定エージェントとの私聊。該当エージェントの該当ワークスペースの agent_logs と私聊履歴（agent_private_messages、ユーザー質問の区切りバー含む）を集約。

クエリパラメータ：

パラメータ	型	必須	説明
`channel`	string	はい	論理チャンネル：`work-group` または `agent:{agent_id}`
`workspace_id`	string (UUID)	はい	ワークスペース ID
`limit`	number	いいえ	最大返却件数。デフォルト 50、最大 100
`before`	string (ISO タイムスタンプ)	いいえ	カーソルページネーション、指定タイムスタンプより前のデータを返却

レスポンス：

json

{
  "code": 0,
  "message": "获取频道日志成功",
  "data": {
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "logical_channel": "work-group",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "logs": [
      {
        "agent_id": null,
        "agent_name": null,
        "agent_title": null,
        "agent_avatar": null,
        "type": "message",
        "data": "プランを立ててください",
        "error_message": null,
        "metadata": {},
        "sender_type": "user",
        "timestamp": "2026-07-07T11:32:58.416Z"
      },
      {
        "agent_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "agent_name": "PlanTester",
        "agent_title": "プランTester",
        "agent_avatar": null,
        "type": "llm_response",
        "data": "...",
        "error_message": null,
        "metadata": {},
        "sender_type": null,
        "timestamp": "2026-07-07T11:32:59.000Z"
      }
    ],
    "has_more": false,
    "next_before": null
  }
}

type の例：message、llm_request、llm_response、tool_call、tool_response、progress、error など。
sender_type：user はユーザー質問（対話の区切りバー）、null はエージェントイベント。
next_before：カーソル。次回リクエストで before に渡してより古いログを取得。null は最古まで到達したことを示します。

リアルタイムイベントストリーム（SSE）

http

GET /openapi/projects/{project_id}/channels/stream?channel=work-group&workspace_id={uuid}&token={token}
Accept: text/event-stream

チャンネル級 SSE：一つの完全チャンネル（channel + workspace_id で組み合わせ）を購読し、該当チャンネル下の全タスクの状態変化・ログ・承認待ちプラン・完了/失敗イベントをリアルタイムに受信します——一つのチャンネルで複数タスクがある場合、全イベントが同一接続に push され、クライアントは data.task_id で各タスクを識別します。

チャンネル級購読はプロジェクトメンバー身元で gate されます（プロジェクトキーは既にプロジェクトメンバーを gate 済み）。同一チャンネルに同プロジェクトの複数キーからタスクが配信される可能性があり、チャンネルビューは同プロジェクトの全キーに可視です（Web UI のプロジェクト内全員可視と対齐）。
チャンネル級は長接続購読であり、チャンネルには常に新規タスクが配信される可能性があるため、接続はクライアントが能動的に切断するまで保持されます。

クエリパラメータ：

パラメータ	型	必須	説明
`channel`	string	はい	論理チャンネル：`work-group` または `agent:{agent_id}`
`workspace_id`	string (UUID)	はい	ワークスペース ID
`token`	string	はい*	アクセストークン。EventSource はカスタムヘッダーを設定できないため URL 経由で渡します。`Authorization: Bearer` ヘッダー使用時は URL 不要

SSE イベント一覧：

イベント	説明
`connected`	接続成功。該当チャンネルの現在のアクティブタスクスナップショット（`active_tasks`：pending/running/planning）を含む
`status_changed`	タスク状態が変化（接続時に各アクティブタスクに対し 1 件ずつ発行し現在状態を同期）
`log`	新しいログが生成された。`data.task_id` が所属タスク、`data.type` がログ種別
`plan_pending`	承認待ちの新しいプランがある。`data.task_id` が所属タスク
`completed`	タスク完了
`failed`	タスク失敗
`cancelled`	タスクキャンセル
`heartbeat`	30 秒ごとのハートビート
`error`	初期化失敗（認証/パラメータエラー）

各イベントの data は task_id を含みます（connected/heartbeat/error を除く）。クライアントはこれに基づき同一チャンネル内の複数タスクのイベントを個別に集計します。connected イベントの data は active_tasks 配列を含み、各項目は {task_id, status, mode, plan_id, started_at} です。

典型的な使い方：単一タスクの進捗を追跡し完了時に切断

チャンネル級は長接続購読です。典型的なフローは「タスクを配信 → 該当ワークスペースのチャンネルを購読 → task_id でフィルタして自分のタスクのみを注目 → 終端イベント（completed/failed/cancelled）受信時に能動的に close()」。EventSource は切断時に自動再接続するため、追加対応は不要です。

// ワークスペース A の work-group にタスク配信後、該当タスクの進捗を追跡し完了で切断
const TASK_ID = '42987a4f-e35b-43e2-bd81-c8a527bdcaba'; // POST /tasks のレスポンスから取得
const PROJECT = 'プロジェクトUUID';
const WORKSPACE = 'ワークスペースAのUUID';
const TOKEN = 'eyJhbG...';

const url = `https://pryfox.ai/openapi/projects/${PROJECT}/channels/stream`
  + `?channel=work-group&workspace_id=${WORKSPACE}&token=${encodeURIComponent(TOKEN)}`;
const es = new EventSource(url);

es.addEventListener('connected', e => {
  const snap = JSON.parse(e.data);
  console.log('接続済み、チャンネルアクティブタスク:', snap.active_tasks);
});

es.addEventListener('log', e => {
  const d = JSON.parse(e.data);
  if (d.task_id !== TASK_ID) return;   // 自分のタスクのみ注目
  console.log(`[${d.type}] ${d.data ?? ''}`);
});

es.addEventListener('status_changed', e => {
  const d = JSON.parse(e.data);
  if (d.task_id === TASK_ID) console.log('状態:', d.status);
});

// プランモードタスク：plan_pending 受信後 POST /plans/{plan_id}/confirm で承認
es.addEventListener('plan_pending', e => {
  const d = JSON.parse(e.data);
  if (d.task_id === TASK_ID) console.log('プラン承認待ち:', d.plan_id);
});

// タスクが終端状態に入ったら接続を閉じる
const closeOnTerminal = e => {
  const d = JSON.parse(e.data);
  if (d.task_id === TASK_ID) { console.log('タスク終了:', d.status); es.close(); }
};
['completed', 'failed', 'cancelled'].forEach(t => es.addEventListener(t, closeOnTerminal));

承認待ちプラン一覧

http

GET /openapi/projects/{project_id}/plans/pending?channel=work-group&workspace_id={uuid}

チャンネル単位で承認待ち（status = proposed）プランを返却します。論理チャンネル + workspace_id の二重パラメータを渡すと、サーバーが完全チャンネルに組み合わせて agent_plans.channel で直接フィルタし、該当ワークスペースの該当チャンネルの承認待ちプランのみを返却します。

論理チャンネル（work-group または agent:{agent_id}）を渡してください。組み合わせ済みの完全チャンネルではありません。:ws:<workspace_id> 接尾辞は自带しないでください。
例：?channel=work-group&workspace_id=A はワークスペース A の群聊の承認待ちプラン、?channel=agent:agent1&workspace_id=A はワークスペース A での agent1 との私聊の承認待ちプランを取得します。

クエリパラメータ：

パラメータ	型	必須	説明
`channel`	string	はい	論理チャンネル：`work-group` または `agent:{agent_id}`
`workspace_id`	string (UUID)	はい	ワークスペース ID

レスポンス：

json

{
  "code": 0,
  "message": "获取待确认计划成功",
  "data": {
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "logical_channel": "work-group",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "plans": [
      {
        "plan_id": "492c1f7a-f20c-4c56-8293-c384b1530a44",
        "agent_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
        "title": "Mock Plan: Verify Open API Flow",
        "description": "...",
        "status": "proposed",
        "session_id": "1e523e38-24fe-42cd-9eb1-76fd03f18c17",
        "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
        "created_at": "2026-07-07T11:33:00.000Z",
        "items": [
          {
            "id": "...",
            "step_number": 1,
            "title": "Confirm endpoint works",
            "description": "...",
            "expected_skill": "",
            "status": "pending"
          }
        ]
      }
    ]
  }
}

各プランの channel は storeAgentPlan が書き込んだ完全チャンネル（群聊 workspace:<wid> / 私聊 agent:<aid>:ws:<wid>）で、クエリ時に組み合わせたチャンネルと一致します。agent_id はプランを生成したエージェントです。channel が agent:{agent_id} の場合、そのエージェントは現在のプロジェクトに属している必要があります。

プランの承認 / 拒否

http

POST /openapi/projects/{project_id}/plans/{plan_id}/confirm

リクエスト本文：

フィールド	型	必須	説明
`confirm`	boolean	はい	`true` で実行を承認、`false` で拒否
`feedback`	string	拒否時必須	拒否理由（`confirm: false` の場合必須）
`workspace_id`	string (UUID)	はい	プランが属するワークスペース。プランのチャンネル（`plan.channel`）から解析したワークスペースと一致する必要があります

json

{
  "confirm": true,
  "feedback": "",
  "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282"
}

ワークスペース帰属チェック：workspace_id は必須であり、プランのチャンネルから解析したワークスペースと一致する必要があります。一致しない場合は 403「计划不属于当前工作空间」が返却されます。
キー帰属チェック：プロジェクトキーで呼び出す場合、現在のキーで作成されたタスクに紐づくプランのみ承認できます。別のキーで作成されたタスクのプランの場合、403「计划不属于当前密钥」が返却されます。タスクに key_id がない場合は許可されます。

レスポンス：

json

{
  "code": 0,
  "message": "计划已确认",
  "data": {
    "plan_id": "492c1f7a-f20c-4c56-8293-c384b1530a44",
    "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
    "status": "confirmed",
    "agent_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

status：confirm: true は confirmed を返し（タスクは running に遷移）、confirm: false は rejected を返します（タスクは cancelled に遷移し、拒否理由は result_summary に記録）。タイムアウトしたセッションは 410 を返します。

ワークスペース管理

第三者はワークスペースを明示的に作成・命名・アーカイブ・削除できます。すべてのワークスペース API はプロジェクトキーに tasks:read（読み取り）または tasks:write（書き込み）が必要です。

ワークスペース一覧

http

GET /openapi/projects/{project_id}/workspaces

プロジェクト下の active + archived のすべてのワークスペースを返却します（論理削除されたものは除外）。各項目にタスク数とアクティブタスクの有無を含みます。

レスポンス：

json

{
  "code": 0,
  "message": "获取工作空间列表成功",
  "data": {
    "workspaces": [
      {
        "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "name": "サポート窓口",
        "description": "エンドユーザー向け問い合わせワークスペース",
        "status": "active",
        "created_by": 12,
        "created_at": "2026-07-07T11:32:58.416Z",
        "updated_at": "2026-07-07T11:32:58.416Z",
        "task_count": 5,
        "has_active_task": false,
        "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
      }
    ]
  }
}

ワークスペース作成

http

POST /openapi/projects/{project_id}/workspaces

ワークスペースを明示的に作成し、任意で命名します。返却される id は以降のタスク作成時の workspace_id として再利用できます。

リクエスト本文：

フィールド	型	必須	説明
`name`	string	いいえ	ワークスペース名。最大 100 文字。省略時はフロントエンドのリストが短縮 UUID にフォールバック
`description`	string	いいえ	ワークスペースの説明

レスポンス：

json

{
  "code": 0,
  "message": "工作空间已创建",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "name": "サポート窓口",
    "description": "エンドユーザー向け問い合わせワークスペース",
    "status": "active",
    "created_by": 12,
    "created_at": "2026-07-07T11:32:58.416Z",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

ワークスペース詳細取得

http

GET /openapi/projects/{project_id}/workspaces/{workspace_id}

レスポンス：

json

{
  "code": 0,
  "message": "获取工作空间详情成功",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "name": "サポート窓口",
    "description": "エンドユーザー向け問い合わせワークスペース",
    "status": "active",
    "created_by": 12,
    "created_at": "2026-07-07T11:32:58.416Z",
    "updated_at": "2026-07-07T11:32:58.416Z",
    "task_count": 5,
    "active_task_count": 0,
    "message_count": 23,
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

task_count：当該ワークスペース下のタスク総数（履歴含む）。
active_task_count：pending/running/planning のアクティブタスク数。
message_count：当該ワークスペースの群聊メッセージ数。

ワークスペース更新

http

PUT /openapi/projects/{project_id}/workspaces/{workspace_id}

名前・説明の変更、active ↔ archived 間の状態切替を行います。アーカイブは可逆で、履歴データは削除されません。少なくとも 1 つの更新可能フィールドを指定する必要があります。

リクエスト本文：

フィールド	型	必須	説明
`name`	string	いいえ	新しい名前。最大 100 文字。空文字列は `null` にクリア
`description`	string	いいえ	新しい説明
`status`	string	いいえ	`active` または `archived`

レスポンス：

json

{
  "code": 0,
  "message": "工作空间已更新",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "name": "サポート窓口 v2",
    "description": "エンドユーザー向け問い合わせワークスペース",
    "status": "archived",
    "created_by": 12,
    "created_at": "2026-07-07T11:32:58.416Z",
    "updated_at": "2026-07-08T09:00:00.000Z",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

ワークスペース級のプランモードデフォルト（plan_mode_enabled）はプロジェクトメンバーが web UI のワークスペース管理ページで設定するもので、オープン API のワークスペース API からは公開されません。第三者がタスクごとにプランモードを制御するには、タスク作成呼び出しの mode フィールドに plan または auto を渡してください。

ワークスペース削除

http

DELETE /openapi/projects/{project_id}/workspaces/{workspace_id}

ワークスペースを論理削除します（status = deleted + deleted_at）。監査のため、履歴メッセージ / ログ / タスク行は保持されます。

アクティブタスクがある場合の削除：ワークスペースにアクティブタスク（pending / running / planning）がある場合でも削除可能（論理削除）です。削除時にプログラムはこれらのタスクを終了します：進行中のストリーミング実行は中止され（Claw へ cancel_message 送信）、タスク記録は cancelled（終端状態）となり、タスク行は監査のため履歴として保持されます。一覧 API の has_active_task フィールドでフロントエンドに警告を表示できます。

復活セマンティクス：論理削除後、同じ workspace_id で再度タスクを配信すると、自動的に active に復活します。したがって、オープン API の第三者にとって「削除」は実質的に「一時停止」であり、管理側の論理削除によって保持しているワークスペース ID がデッドロックすることはありません。

レスポンス：

json

{
  "code": 0,
  "message": "工作空间已删除",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "terminated_tasks": 2
  }
}

terminated_tasks：削除時に終了されたアクティブタスクの数。当該ワークスペース下の対話データ（群聊/私聊メッセージは論理削除、ログ/プランは物理削除）および Claw 記憶データも消去され、メインチャンネルのデータ（workspace_id IS NULL）は影響を受けません。復活したワークスペースは空白のコンテキストから再開され、以前の対話は保持されません。

エージェント一覧取得（内部 API）

http

GET /api/projects/{project_id}/agents?page=1&limit=20&status=active&search=Plan

ワークスペース内のエージェントはコーディネーターが自動選択するため、タスク作成時に agent_id を指定する必要はありません。プロジェクト内にどのようなエージェントが存在するか、その設定を確認したい場合にこのインターフェースを使用します。このインターフェースは内部 /api/ プレフィックスを使用し、/openapi/ ではない点に注意してください。

権限要件：プロジェクトキーに employees:read が必要です。

クエリパラメータ：

page：ページ番号。デフォルト 1
limit：1 ページあたりの件数。デフォルト 20、最大 100
status：状態で絞り込み
search：名前またはタイトルであいまい検索

レスポンス：

json

{
  "code": 0,
  "message": "获取智能体列表成功",
  "data": {
    "agents": [
      {
        "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "name": "PlanTester",
        "title": "プランTester",
        "avatar": null,
        "role": "member",
        "is_system": false,
        "model": { "id": "...", "name": "mock-llm" },
        "status": "idle",
        "status_text": "等待任务",
        "device": null,
        "self_reflect": false,
        "plan_mode_enabled": true,
        "stats": {},
        "skill_count": 0,
        "created_at": "2026-07-06T...",
        "updated_at": "2026-07-06T..."
      }
    ],
    "user_role": "member",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

エージェントの plan_mode_enabled はそのエージェント自身のプランモードトグル（エージェント作成時に設定）であり、ワークスペース級プランモードデフォルトとは別の概念です。status は現在のユーザーの進行中タスクの有無に影響されます（進行中タスクがある場合は working を表示）。

一般的なエラーコード

HTTP ステータス	説明
400	パラメータエラー。例：空の内容、無効な workspace_id、拒否時に feedback 不足、無効な status 値
401	未認証またはトークン失効
403	プロジェクト権限なし、キーに必要な操作権限がない、またはタスク/プランが現在のキー/ワークスペースのものではない
404	タスク、エージェント、プラン、ワークスペースが存在しない
409	プランは既に処理済みで再確認不可
410	プラン確認セッションがタイムアウト
429	認証 API のレート制限
500	サーバー内部エラー

呼び出し例

bash

# 1. トークン取得
TOKEN_RESP=$(curl -s -X POST https://pryfox.ai/openapi/auth/project-key \
  -H 'Content-Type: application/json' \
  -d '{"key":"proj_xxxxx_xxxxxx"}')
TOKEN=$(echo "$TOKEN_RESP" | jq -r '.data.token')
CSRF=$(echo "$TOKEN_RESP" | jq -r '.data.csrfToken')
PROJECT='プロジェクトUUID'
WORKSPACE='任意のワークスペースUUID'   # ワークスペース API で作成するか、初回タスクで暗黙的に作成

# 2. ワークスペース作成（任意、命名管理用）
curl -s -X POST "https://pryfox.ai/openapi/projects/$PROJECT/workspaces" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"name":"サポート窓口","description":"エンドユーザー向け問い合わせワークスペース"}'

# 3. タスク作成（ワークスペース指定 + 群聊チャンネル + プラン確認モード）
TASK_RESP=$(curl -s -X POST "https://pryfox.ai/openapi/projects/$PROJECT/tasks" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: $CSRF" \
  -d "{\"content\":\"プランを立ててください\",\"workspace_id\":\"$WORKSPACE\",\"channel\":\"work-group\",\"mode\":\"plan\"}")
TASK_ID=$(echo "$TASK_RESP" | jq -r '.data.task_id')

# 4. このワークスペースの work-group チャンネルの承認待ちプラン一覧
PENDING=$(curl -s "https://pryfox.ai/openapi/projects/$PROJECT/plans/pending?channel=work-group&workspace_id=$WORKSPACE" \
  -H "Authorization: Bearer $TOKEN")
PLAN_ID=$(echo "$PENDING" | jq -r '.data.plans[0].plan_id')

# 5. プラン承認
curl -s -X POST "https://pryfox.ai/openapi/projects/$PROJECT/plans/$PLAN_ID/confirm" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: $CSRF" \
  -d "{\"confirm\":true,\"workspace_id\":\"$WORKSPACE\"}"

# 6. このワークスペースの work-group チャンネルのリアルタイムイベントストリームを購読（task_id でフィルタ、終端で切断）
#    EventSource はカスタムヘッダーを設定できないため token は URL 経由で渡す
#    JS クライアントで new EventSource(...) を使い、data.task_id で自分のタスクをフィルタし、
#    completed/failed/cancelled 受信後に es.close()（チャンネル級長接続は自動で閉じない）

# 7. このワークスペースの全タスク一覧
curl -s "https://pryfox.ai/openapi/projects/$PROJECT/tasks?workspace_id=$WORKSPACE&limit=20" \
  -H "Authorization: Bearer $TOKEN"

# 8. このワークスペースの work-group チャンネルの過去ログを取得（接続前に既存イベントを補完）
curl -s "https://pryfox.ai/openapi/projects/$PROJECT/channels/logs?channel=work-group&workspace_id=$WORKSPACE&limit=50" \
  -H "Authorization: Bearer $TOKEN"

オープン API ​

基本情報 ​

認証方式 ​

1. トークン取得 ​

2. インターフェース呼び出し ​

ワークスペースとチャンネル ​

インターフェース一覧 ​

タスク作成 ​

タスク一覧 ​

タスク状態取得 ​

チャンネルログ取得 ​

リアルタイムイベントストリーム（SSE） ​

典型的な使い方：単一タスクの進捗を追跡し完了時に切断 ​

承認待ちプラン一覧 ​

プランの承認 / 拒否 ​

ワークスペース管理 ​

ワークスペース一覧 ​

ワークスペース作成 ​

ワークスペース詳細取得 ​

ワークスペース更新 ​

ワークスペース削除 ​

エージェント一覧取得（内部 API） ​

一般的なエラーコード ​

呼び出し例 ​

オープン API

基本情報

認証方式

1. トークン取得

2. インターフェース呼び出し

ワークスペースとチャンネル

インターフェース一覧

タスク作成

タスク一覧

タスク状態取得

チャンネルログ取得

リアルタイムイベントストリーム（SSE）

典型的な使い方：単一タスクの進捗を追跡し完了時に切断

承認待ちプラン一覧

プランの承認 / 拒否

ワークスペース管理

ワークスペース一覧

ワークスペース作成

ワークスペース詳細取得

ワークスペース更新

ワークスペース削除

エージェント一覧取得（内部 API）

一般的なエラーコード

呼び出し例