REST インターフェース

特別な記載がない限り、すべてのインターフェースはリクエストヘッダーにテナント API Key が必要です：

Authorization: Bearer <テナントAPI Key>

既定のアドレスは http://localhost:8787、デモテナントは demo（apiKey は初回起動時にランダム生成されログに出力されます）。このページは連携開発の参考であり、 通常のユーザーは気にする必要はありません。

サーバーの起動

# モデル Key なしでも起動可能（認証/セッション/インターフェースは試せる。会話だけエラーになる）
pnpm run server

# 実際のモデルを使う（推奨）
OPENAI_API_KEY=sk-... OPENAI_MODEL=gpt-4o-mini pnpm run server

主な環境変数：PORT（既定 8787）、DATA_DIR（既定 ./.zqagent_data）、 APPROVAL_TIMEOUT_SECONDS（承認/質問の保留タイムアウト、既定 900）、 TENANT_ID / TENANT_API_KEY / MODEL（デモテナント）。

認証

export BASE=http://localhost:8787
export TOKEN=zk_xxxx   # 起動ログ「已创建演示租户」の行の apiKey

# ヘルスチェック（公開）
curl -s $BASE/healthz                 # => {"status":"ok"}

# Key なし → 401
curl -s -o /dev/null -w "%{http_code}\n" $BASE/api/v1/sessions   # => 401

# 正しい Key → 200
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" $BASE/api/v1/sessions

主要エンドポイント早見表

セッション

メソッド	パス	説明
GET	/healthz	ヘルスチェック（公開）
POST	/api/v1/sessions	セッションを作成
GET	/api/v1/sessions	セッションを一覧
GET	/api/v1/sessions/{id}	セッションを取得
PATCH	/api/v1/sessions/{id}	セッション名を変更
DELETE	/api/v1/sessions/{id}	セッションを削除
GET	/api/v1/sessions/{id}/state	セッション状態（保留中の承認/質問を含む）
PATCH	/api/v1/sessions/{id}/model	セッションのモデルを切り替え
PATCH	/api/v1/sessions/{id}/mode	権限モードを切り替え（plan / interactive / auto / discuss）
PATCH	/api/v1/sessions/{id}/draft	入力欄の下書きを保存（空文字でクリア）
POST	/api/v1/sessions/{id}/turns	タスクを投入
POST	/api/v1/sessions/{id}/steer	実行中に補足情報
POST	/api/v1/sessions/{id}/interrupt	現在のタスクを中断
POST	/api/v1/sessions/{id}/resume	セッションを再開
GET	/api/v1/sessions/{id}/events	イベントストリーム（ポーリングまたは SSE、?since= で差分）
GET	/api/v1/sessions/{id}/approvals	承認待ち一覧
POST	/api/v1/sessions/{id}/approvals/{aid}	承認に回答
GET	/api/v1/sessions/{id}/questions	回答待ち一覧
POST	/api/v1/sessions/{id}/questions/{qid}	質問に回答

プロジェクトとノード

メソッド	パス	説明
GET / POST	/api/v1/projects	プロジェクトの一覧 / 作成（作成時に作業ディレクトリを指定）
DELETE	/api/v1/projects/{id}	プロジェクトを削除
GET	/api/v1/models	利用可能なモデル一覧
GET / PUT	/api/v1/config	ノード設定の表示 / 更新
GET / PUT	/api/v1/node/llm	ノード既定モデルの表示 / 設定
GET	/api/v1/node/host	ノードホスト情報
GET	/api/v1/tools	ツール一覧
GET	/api/v1/mcp	MCP サーバー一覧
PUT	/api/v1/mcp	MCP 設定を一括置換（プロジェクトの .agent/mcp.json に書き込み。プラットフォーム配信時は 409）
POST	/api/v1/mcp/test	単一 MCP サーバーの接続テスト（保存なし）

使用量とコスト

メソッド	パス	説明
GET	/api/v1/usage/summary	使用量サマリー（期間 / モデル別）
GET	/api/v1/usage/records	明細レコード
GET	/api/v1/usage/export	CSV エクスポート
GET / PUT	/api/v1/usage/pricing	価格表の表示 / 変更
POST	/api/v1/usage/rebuild	サマリーを再構築
POST	/api/v1/usage/verify	台帳を検証

リモート接続とペアリング

メソッド	パス	説明
GET	/api/v1/fleet/status	ノード接続状態
POST	/api/v1/fleet/enroll	接続コードで接続（zqagent link が呼ぶ）
POST	/api/v1/fleet/unlink	接続を解除
GET	/api/v1/fleet/pairing	クラウド接続のペアリング情報（ゲートウェイアドレス + 名前空間/キー + nodeId）
GET / POST	/api/v1/notifications	通知チャネルの表示 / 追加
DELETE	/api/v1/notifications/{id}	通知チャネルを削除

クイックスタート

# セッションを作成
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini"}' $BASE/api/v1/sessions
# => {"data":{"sessionId":"e4df66d6...","status":"idle",...}}

export SID=e4df66d6...   # 返された sessionId に置き換え

# タスクを投入（即時返却、バックグラウンドで非同期実行）
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"input":"こんにちは、自己紹介してください"}' $BASE/api/v1/sessions/$SID/turns
# => {"data":{"accepted":true,"status":"running"}}

# イベントをポーリング（since カーソルで差分取得）
curl -s "$BASE/api/v1/sessions/$SID/events?since=0"

# リアルタイム購読（SSE）
curl -N -H "Authorization: Bearer $TOKEN" -H "Accept: text/event-stream" \
  $BASE/api/v1/sessions/$SID/events

セッションがタスク実行中の場合、POST /turns は自動的に補足情報として現在のタスクに注入されます （{"data":{"accepted":true,"status":"steering"}} を返す）。エラーにはなりません。

承認と質問

モデルが副作用のある操作（ファイル書き込み、コマンド実行など）を要求すると保留して承認を待ちます。ask_user などのツールを呼ぶと 保留して回答を待ちます。

# 承認待ち一覧を表示（id はツール呼び出し ID）
curl -s -H "Authorization: Bearer $TOKEN" $BASE/api/v1/sessions/$SID/approvals

# 承認に回答：once | always_tool | always_command | deny
#   always_command は run_shell のみ有効
export AID=call_xxx
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"decision":"once"}' $BASE/api/v1/sessions/$SID/approvals/$AID

# 質問に回答
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"answer":"続けて"}' $BASE/api/v1/sessions/$SID/questions/qid_xxx

マルチテナント分離

各テナントは自分の API Key で自分のセッションにアクセスします。テナント A の Key でテナント B のセッションにアクセスすると 404 を返します。

エラーコード早見表

HTTP	code	状況
401	unauthorized	Key なし / Key 無効
404	not_found	セッションが存在しない / 未知のルート / テナント越えアクセス
409	not_running	明示的な steer 時にセッションが実行中でない
409	has_pending_interaction	未決の承認/質問があり、新しいタスクを投入できない
400	bad_request	body が不正な JSON / input が空
400	invalid_decision	decision が不正、または run_shell 以外に always_command を送信