ParallelSandboxアプリを開く

REST

api.parallelsandbox.com と log.parallelsandbox.com の REST エンドポイント。アプリやスクリプト向けで、ボックスのスクリーンショットや録画の新しい URL など、エージェントにツールがないことにも使います。

Web とデスクトップアプリ、エージェント以外のもの、そしてエージェントに MCP ツールがない用途（たとえば、ボックスのスクリーンショットと録画の URL を取り直す GET /v1/boxes/{id}/media）のためのものです。同じ認証情報を Authorization: Bearer <トークン> で使います。トークンはアカウントの psbx_ API キー、または接続済みクライアントの OAuth アクセストークン（1 時間。キーの入手方法）です。特に書いていないものは https://api.parallelsandbox.com です。

エンドポイント 用途
/v1/auth/github GitHub ログイン
/v1/keys API キーの作成、一覧、失効。アプリにサインインしたセッションからだけ（API キーや OAuth トークンではキーを管理できない）。POST は OAuth に対応しないツール向けのキーを作り、OAuth サインインで発行されたものは一覧に出ない
/v1/boxes ボックスの一覧（起動が新しい順に最大 200 個。?all=1 で停止したものも）、起動（ここでは goal は任意）、参照、停止。一覧には sceneUrl、webUrl、各 web サービスの url、goal、agent、screenInUse、screenActive、posterUrl が入る（どの会話がボックスを使っているか）。停止したボックスにも最新の posterUrl は付くが、review は付かない：ボックスを止めるとカードは閉じられ、カードの画像はもう取れない
PUT /v1/boxes/{id}/orientation 準備完了のボックスの AI 画面を portrait または landscape に変更する。screen-orientation 対応のイメージが必要で、変更後の向きを返す
POST /v1/boxes/{id}/review/done ボックスの待っている sandbox_review のカードを、アプリと同じく確認済みにする。GET /v1/boxes は待っているカードを review として返す
POST /v1/boxes/{id}/wake 凍結したボックスを復帰させる（使用として数える。アカウントにクレジットがないと 402）。ボックスの状態を返す
GET /v1/boxes/{id}/media このボックスで直近 7 日間に撮られた、画面が残っているステップ（sandbox_exec で自動録画されたもの、sandbox_shot で撮った・録画したもの）。新しい 200 件まで、古い順。止めたボックスでも取得できます：{"keepDays": 7, "steps": [...]}。各ステップのフィールドは sandbox_status の steps[] と同じで（at、kind、summary、ok、それに該当するときだけの target、note、actor、detail、ms、exitCode、signal、timedOut、error）、ほかに media[] があり、それぞれ kind（video か image）、url、bytes、動画には durationSec が付きます。URL は呼ぶたびに署名し直され、少なくとも 1 時間有効
DELETE /v1/boxes/{id}/media このボックスに保存されたスクリーンショット、録画（ステップごとに自動で録画されたものを含む）、凍結時のポスター、レビューカードの画像を削除します。動いているボックスにも止めたボックスにも使えます。{"ok":true,"deleted":N,"bytes":B} を返します。アクティビティ記録は残り、その後の GET /v1/boxes/{id}/media は空の steps を返します。別のアカウントのボックスは 404。途中で失敗すると 502 で、もう一度呼べば残りを削除します
DELETE /v1/boxes/{id}/events ボックスの活動記録を削除します。アプリのタイムラインのステップ（人がそこで見られる説明とコマンドも）、sandbox_status の steps[]、それらのステップで撮ったスクリーンショットと録画です。どうやって作ったかを見せるべきでない相手、たとえば別の言語を読む審査員にボックスを渡す前に使います。{"ok":true,"deleted":N,"mediaDeleted":M} を返し、その後の呼び出しは通常どおり記録されます。呼べるのはアカウント本人だけで、確認リンクからは呼べません。別のアカウントのボックスは 404 です
DELETE /v1/build-cache アカウントの sandbox_build キャッシュをすべて削除し、{"ok":true,"deleted":N,"bytes":B} を返します。以後、同じフィンガープリントの sandbox_build はビルドし直します（reused: false）。途中で失敗すると 502 で、もう一度呼んでください
POST /v1/agents/{id}/heartbeat 会話 {id}（その X-Psbx-Agent）がまだ開いている。本文は {"client": "<MCP クライアント名>"}、60 秒ごと。{"ok":true} を返す
POST /v1/agents/{id}/leave 会話 {id} が閉じられた。それが最後に使ったボックスは、人を待っていなければ「AI は手を止めました」と表示される。{"ok":true} を返す
POST /v1/boxes/{id}/exec 人としてコマンドを実行する。アプリのコマンド欄が使うもの：{"cmd", "cwd", "env", "timeoutSec", "background", "note"} を受け取り、sandbox_exec のフィールドと "actor": "human" を返す。ボックスが引き継がれている間も実行され、記録されず（スクリーンショットも動画もなし）、steps[] とアプリでのそのステップは actor: human になる。AI のステップはこうして作られるものではない。エージェントの呼び出しで何が記録されるかを試すには、MCP で sandbox_exec を呼ぶ
GET /v1/files/{token} sandbox_get、sandbox_shot、sandbox_exec の outputUrl が返すダウンロードリンク。キーは不要（リンク自体が権限で、1 時間有効）。数分間有効なストレージの URL にリダイレクト（302）する
/v1/boxes/{id}/sync tar.gz をボックスにアップロード（アダプターの sandbox_sync が使う）
/v1/boxes/{id}/screencast ライブ画面、WebSocket
/v1/boxes/{id}/input マウスとキーボードの入力
/v1/takeovers 保留中の引き継ぎリクエスト。それぞれ takeoverUrl、その token と appLink（parallelsandbox://box/<id>?t=<token>）付き
/v1/takeovers/{id}/return メモを添えてボックスを返す
GET、PUT /v1/box-access ボックス URL の IP 許可リスト：{ "allowedIps": [...] }、[] でオフ（その他の事実）
GET /v1/secrets、PUT /v1/secrets/{name}、DELETE /v1/secrets/{name} シークレットの管理。人は app.parallelsandbox.com の設定 → Secrets でも追加、置き換え、削除ができます
/v1/versions 公開済みのバージョン。DELETE /v1/versions/{id} はバージョンの記録を削除し、同じイメージタグを使うバージョンがアカウントにほかになければレジストリのイメージも削除して {"ok":true,"imageDeleted":true} を返します。イメージを残したときは imageDeleted が false で reason が付きます（例：image is still used by 1 other version(s): billing/v2）。レジストリで削除できなかったときは 502 で、バージョンの記録は残るので再試行できます
/v1/environments 環境、接続（コネクタのトークン）、プライベートアドレス、サービス設定（.env のアップロードまたは AWS ECS からの取り込み）。すべてのエンドポイントは環境に
/v1/aws 取り込みに使う読み取り専用の AWS ロール。/v1/aws/ecs/services で ECS サービスを一覧
/v1/connector コネクタが接続する WebSocket（接続トークン付き）
GET /v1/usage、GET /v1/usage/events 種類ごとの使用量合計と使用量イベント（since、until、box_id、limit）
GET /v1/credits 残高、バケット、プラン、クレジットが尽きてから 24 時間の間は boxesKeptUntil
GET /v1/billing/catalog プランと追加パック（キー不要）
/v1/billing/checkout、/v1/billing/portal Stripe Checkout と顧客ポータル
/v1/billing/webhook Stripe webhook
POST /v1/projects（log.parallelsandbox.com） ログプロジェクトの作成。書き込みキーはこのときだけ返る
GET、PATCH、DELETE /v1/projects/{id}（log.parallelsandbox.com） ログプロジェクトの参照、許可するオリジンの変更、削除
POST /v1/projects/{id}/write-key（log.parallelsandbox.com） 書き込みキーの交換。古いキーはすぐ無効
/v1/projects/{id}/sourcemaps（log.parallelsandbox.com） ソースマップのアップロードと一覧

すべてのツールとトピックはツールリファレンスに並んでいます。

API keys

OAuth に対応しないツールは psbx_ API キーを使えます。AI がアプリのログイン済みセッションから、名前を指定して POST /v1/keys で作成します。キーの表示は一度だけです。GET /v1/keys で一覧、DELETE /v1/keys/{id} で失効できます。API キーや OAuth アクセストークンではキーを管理できません。通常のインストールは OAuth アダプターを使い、手動でキーを作る必要はありません。