ParallelSandbox打開 app

REST

api.parallelsandbox.com 與 log.parallelsandbox.com 的 REST 端點，給 app、腳本，以及 agent 沒有工具可做的事，例如重新取得箱子截圖與錄影的網址。

給 web 與桌面 app、任何不是 agent 的東西，以及 agent 沒有 MCP 工具可用的事，例如重拿箱子截圖與錄影的網址（GET /v1/boxes/{id}/media）。同一份憑證，Authorization: Bearer <token>，token 是帳號的 psbx_ API key，或已接上的 client 的 OAuth access token（一小時；key 從哪來），沒特別註明的都在 https://api.parallelsandbox.com。

端點 用途
/v1/auth/github GitHub 登入
/v1/keys 建立、列出與撤銷 API key；只能在 app 登入後的 session 裡用（API key 與 OAuth token 都不能管理 key）；POST 是替不支援 OAuth 的工具建 key，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 卡片標成驗完，跟 app 做的一樣；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），另有 media[]：每一個有 kind（video 或 image）、url、bytes，影片還有 durationSec；url 每次呼叫都重簽，至少一小時有效
DELETE /v1/boxes/{id}/media 刪掉這個箱子保存的截圖、錄影（含每一步自動錄的）、凍結封面與交件卡片圖；跑著的與已停的箱子都能用。回 {"ok":true,"deleted":N,"bytes":B}；活動記錄留著，之後 GET /v1/boxes/{id}/media 回空的 steps。別的帳號的箱子回 404；刪到一半失敗回 502，再呼叫一次就會把剩下的刪掉
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）還開著；body {"client": "<MCP client 名稱>"}，每 60 秒一次；回 {"ok":true}
POST /v1/agents/{id}/leave 對話 {id} 關掉了：它最後用的箱子顯示為「AI 停手了」，除非在等人；回 {"ok":true}
/v1/boxes/{id}/sync 把 tar.gz 上傳進箱子（轉接器的 sandbox_sync 用這個）
/v1/boxes/{id}/screencast 即時畫面，WebSocket
/v1/boxes/{id}/input 滑鼠鍵盤輸入
/v1/takeovers 待接手的請求
/v1/takeovers/{id}/return 交還箱子並留話
GET、PUT /v1/box-access 箱子網址的 IP 白名單：{ "allowedIps": [...] }，[] 關掉（其他事實）
GET /v1/secrets、PUT /v1/secrets/{name}、DELETE /v1/secrets/{name} 管理 secrets；人也可以在 app.parallelsandbox.com 的設定 → Secrets 新增、換值、刪除
/v1/versions 已發布的版本。DELETE /v1/versions/{id} 刪一筆版本紀錄；帳號裡沒有別的版本用同一個 image tag 時連 registry 裡的 image 一起刪，回 {"ok":true,"imageDeleted":true}；沒刪 image 時 imageDeleted 是 false 並附 reason（例如 image is still used by 1 other version(s): billing/v2）。registry 刪不掉時回 502、版本紀錄留著，可以重試
/v1/environments 環境、連線（連接器 token）、內網位址、服務設定（上傳 .env 或從 AWS ECS 匯入）；每個端點在環境
/v1/aws 匯入用的 AWS 唯讀角色；/v1/aws/ecs/services 列出 ECS 服務
/v1/connector 連接器連進來的 WebSocket，帶連線 token
GET /v1/usage、GET /v1/usage/events 依種類加總的用量，與用量事件（since、until、box_id、limit）
GET /v1/credits 餘額、分桶、方案，以及點數用完後 24 小時內的 boxesKeptUntil
GET /v1/billing/catalog 方案與加購包（不用 key）
/v1/billing/checkout、/v1/billing/portal Stripe Checkout 與客戶入口
/v1/billing/webhook Stripe webhook
POST /v1/projects（log.parallelsandbox.com） 建立 log project；write key 只在這次回傳
GET、PATCH、DELETE /v1/projects/{id}（log.parallelsandbox.com） 查看 log project、改允許的 origin、刪除
POST /v1/projects/{id}/write-key（log.parallelsandbox.com） 換 write key；舊的立刻失效
/v1/projects/{id}/sourcemaps（log.parallelsandbox.com） 上傳與列出 source map

所有工具與主題都列在工具參考。

API keys

不支援 OAuth 的工具可以使用 psbx_ API key。由 AI 使用 app 登入後的 session 呼叫 POST /v1/keys 建立，帶上名稱；key 只會顯示一次。GET /v1/keys 列出、DELETE /v1/keys/{id} 撤銷。API key 與 OAuth access token 都不能管理 key。一般安裝使用 OAuth 轉接器，不需要手動建 key。