Clousd API 參考文件。

Clousd API v1 的所有路由，共 71 個操作，依使用情境分組。參數、請求主體和回應請見 OpenAPI 檔案。

每個請求

# base URL
https://api.clousd.com/v1

# header
Authorization: Bearer cl_live_your_key

# errors are JSON
{ "error": "busy", "message": "…" }

所有路由。

項目	值	說明
基本網址（Base URL）	https://api.clousd.com/v1	僅限 HTTPS，請求與回應皆為 JSON
驗證	Authorization: Bearer cl_live_…	金鑰在控制台建立，可限定為 read 或 control 權限，以及指定的裝置清單
耗時操作	202 Accepted → GET /v1/jobs/{id}	建立、開機、恢復等呼叫會回傳一項需要輪詢的工作
錯誤	{ "error": "busy", "message": "…" }	一個供程式判斷的簡短代碼，加上一段給人看的訊息
完整規格	openapi-v1.yaml	OpenAPI 3.1，含參數、請求主體與回應

方法	路由	用途
GET	/v1/schedules	這組金鑰的排程
POST	/v1/schedules	自動執行的任務：每天、每小時，或在你呼叫時執行
POST	/v1/schedules/{id}/toggle	暫停或繼續排程
POST	/v1/schedules/{id}/delete	刪除排程
POST	/v1/runs	用白話把任務交給一台或多台手機
GET	/v1/runs	這組金鑰的執行紀錄，最新的在前
GET	/v1/runs/{id}	單次執行：狀態、結果、structured_output，以及它正在等待的卡片
DELETE	/v1/runs/{id}	刪除已結束的執行，連同步驟和截圖
GET	/v1/runs/{id}/events	以 Server-Sent Events 推送即時事件
GET	/v1/runs/{id}/trajectory	每一步：工具、目標、結果、畫面是否保留
GET	/v1/runs/{id}/steps/{n}.jpg	第 n 步之前的畫面
POST	/v1/runs/{id}/answer	回覆執行的卡片：問題（answer）或授權（allow / decline）
POST	/v1/runs/{id}/message	傳訊息給執行中的 Agent，它會在下一步之前讀取
POST	/v1/runs/{id}/cancel	停止執行
POST	/v1/schedules/{id}/run	立即開始排程，也就是 trigger=api 的觸發方式
GET	/v1/credentials	已儲存的登入資訊：套件名稱、名稱和哪些欄位已設定；絕不回傳值
POST	/v1/credentials	為 App 儲存登入資訊
POST	/v1/credentials/{id}/fields	設定登入資訊的某個欄位
DELETE	/v1/credentials/{id}/fields/{type}	移除登入資訊的某個欄位
DELETE	/v1/credentials/{id}	刪除登入資訊

方法	路由	用途
GET	/v1/devices	這組金鑰看得到的裝置
POST	/v1/devices	建立裝置（費用記在 API 金鑰所屬的帳戶）
GET	/v1/devices/{name}	單一裝置
POST	/v1/devices/{name}/start	裝置開機
POST	/v1/devices/{name}/stop	裝置關機（狀態會保留；關機的裝置不收費）
POST	/v1/devices/{name}/restart	重新啟動裝置
GET	/v1/devices/{name}/ice	這台裝置 WebRTC 觀看端的 ICE 伺服器：裝置所在主機的 TURN 與臨時憑證（read 金鑰即可）
GET	/v1/devices/{name}/quality	各類別品質分數（最近一次量測）
POST	/v1/devices/{name}/reset	把裝置重設為全新狀態：清除 App 和資料，手機恢復如新（機型與 Android 版本不變，1–5 分鐘）
GET	/v1/devices/{name}/screenrecord	錄製幾秒鐘的畫面
POST	/v1/devices/{name}/label	替手機取一個人和 Agent 都能分辨的名稱（例如「Pixel QA」）；留空則恢復為「機型 #N」
GET	/v1/balance	帳戶金額：餘額、每日花費、剩餘時數、續訂資訊，以及要提醒使用者的事項
GET	/v1/models	可用來建立裝置的機型

方法	路由	用途
GET	/v1/devices/{name}/observe	一次呼叫重新查看手機：截圖、UI 樹和畫面上的 App
POST	/v1/devices/{name}/act	執行一個動作，然後等畫面不再變化
POST	/v1/devices/{name}/op	一個核心基本操作（與 Lusiesta 核心協定一對一對應）

方法	路由	用途
GET	/v1/devices/{name}/screenshot	以 PNG 回傳畫面；帶 w 參數時回傳較小的 JPEG（最多快取 10 秒，要最新畫面請用 /observe）
POST	/v1/devices/{name}/action	在手機上執行一個動作（不等待）
POST	/v1/devices/{name}/input	觸控、按鍵、文字、捲動、剪貼簿、旋轉（需要即時畫面工作階段）
GET	/v1/devices/{name}/logs	最近的 logcat 紀錄
GET	/v1/devices/{name}/stream	即時畫面數據：fps、位元率、觀看端延遲、ABR 層級（read 金鑰即可）
POST	/v1/devices/{name}/stream	WebRTC：傳入 SDP offer，回傳 SDP answer；主體帶 bitrate_kbps 時則改為固定畫質層級（control 金鑰）
POST	/v1/devices/{name}/stream/probe	即時觀看端的延遲測試：拉下通知欄 600 毫秒並回傳閘道時鐘（control 金鑰，每台裝置每 5 秒最多一次）

方法	路由	用途
PUT	/v1/devices/{name}/files	把檔案放到手機上（push）：主體即檔案，路徑須在 /sdcard/ 或 /data/local/tmp/ 底下
POST	/v1/devices/{name}/media	把媒體庫的檔案放到手機上，就像用這台手機拍的（push）；移除放進去的檔案（clean）；或列出它們
GET	/v1/media	媒體庫：照片和影片及其 id
POST	/v1/media	上傳照片或影片：{name, data_b64, folder}，最大 25 MB
POST	/v1/media/send	把媒體庫檔案複製到手機相簿

方法	路由	用途
GET	/v1/webhooks	這組金鑰的 Webhook，以及可訂閱的六種事件（任務完成、失敗、取消、等待，手機異常與恢復）
POST	/v1/webhooks	訂閱一個 https 網址
GET	/v1/webhooks/{id}	單一 Webhook
DELETE	/v1/webhooks/{id}	刪除
POST	/v1/webhooks/{id}/rotate	新的簽章密鑰（只顯示一次）
POST	/v1/webhooks/{id}/toggle	暫停或繼續傳送
POST	/v1/webhooks/{id}/test	立即送出測試事件
GET	/v1/webhooks/{id}/deliveries	近期傳送紀錄，含狀態與回應時間