HTTP ルート

HTTP API は表面別にまとまっています。以下の各パスはエンドポイント別の詳細仕様ページへリンクします。

認証

GET /health は公開されています。SNA ランタイムのその他すべてのルートは /api/sna-port、SSE ルート、chat image 取得も含めて Authorization: Bearer <authToken> を要求します。トークンがない場合や一致しない場合は 401、許可されていない browser origin は 403 を返します。

SDK が管理する host では、handle.connection を SnaClient または SnaProvider に渡します。別の app-owned discovery endpoint が信頼済み renderer に { baseUrl, authToken } を返すことはできますが、SNA ランタイム自身の /api/sna-port ルートは引き続き保護されます。

システム

メソッド	パス	用途
`GET`	`/health`	Health check
`GET`	`/api/sna-port`	現在の SNA API ポート取得

セッション

メソッド	パス	用途
`POST`	`/agent/sessions`	セッションレコード作成
`GET`	`/agent/sessions`	セッション一覧取得
`PATCH`	`/agent/sessions/{id}`	label、meta、cwd を更新
`DELETE`	`/agent/sessions/{id}`	セッション、履歴、runtime chain、保留中の権限を削除

エージェントライフサイクル

メソッド	パス	用途
`POST`	`/agent/start`	セッション内でエージェントを spawn
`POST`	`/agent/send`	メッセージ送信
`POST`	`/agent/restart`	終了後に re-spawn
`POST`	`/agent/resume`	正規化履歴で再開
`POST`	`/agent/interrupt`	現在のターンを取り消し
`POST`	`/agent/set-model`	ランタイム中にモデル変更
`POST`	`/agent/set-permission-mode`	ランタイム中に権限モード変更
`PATCH`	`/agent/session`	統一設定 mutator
`POST`	`/agent/kill`	エージェントプロセス終了
`GET`	`/agent/status`	状態スナップショット

単発呼び出し

メソッド	パス	用途
`POST`	`/agent/run-once`	1 回実行して結果返却
`POST`	`/agent/run-once/stream`	SSE イベントで単発実行
`POST`	`/agent/completion`	単発 completion

権限

メソッド	パス	用途
`POST`	`/agent/permission-request`	権限要求を送信して待機
`POST`	`/agent/permission-respond`	承認または拒否
`GET`	`/agent/permission-pending`	pending 要求一覧

モデルとイベント

メソッド	パス	用途
`POST`	`/agent/list-models`	ランタイムモデル introspection
`GET`	`/agent/events`	セッションイベント SSE ストリーム

Chat (正規化履歴表面)

メソッド	パス	用途
`GET`	`/chat/sessions`	DB の chat セッション一覧
`POST`	`/chat/sessions`	chat セッション作成
`DELETE`	`/chat/sessions/{id}`	chat セッション削除
`GET`	`/chat/sessions/{id}/messages`	メッセージ一覧
`POST`	`/chat/sessions/{id}/messages`	メッセージ追加
`DELETE`	`/chat/sessions/{id}/messages`	メッセージをクリア
`GET`	`/chat/images/{sessionId}/{filename}`	画像 embed を提供

レスポンス形

ほとんどの SDK-facing レスポンスは server/api-types.ts の envelope に従います。streaming と binary エンドポイントは wire-native なレスポンス本文を使います。正確な schema はライブ OpenAPI ドキュメントで確認してください。

type ApiResponse<T> =
  | { status: "ok"; data: T }
  | { status: "error"; message: string; code?: string };

HTTP ルート

目次