Automation API reference
Last updated:Nov 13, 2026
The base address of the automation API is https://app.yunyoo.ai/api; every path below goes after it. Send Authorization: Bearer <machine token>. For issuing machine tokens and their scopes, see Automation overview.
The platform checks request signatures on these endpoints, and the official command line signs its requests automatically. For your own programs, use the remote form of MCP or call the command-line tool; the signing scheme is not published yet.
Every response has the shape {"code": 0, "data": …, "msg": "…"}. A code of 0 means success; for other values, see Error codes. When rate limited, the API returns HTTP 429, error code 53009 and a Retry-After header. When confirmations are enforced, high-risk actions are held first and return 53010 with a confirmation in data.confirmation; after the user approves it, resend the same request with the header X-Yunyoo-Confirmation: <confirmation ID>. The X-Yunyoo-Intent header can state what the call is for, and the confirmation page shows it to the user. With traceparent, the same trace ID is recorded in the run report.
Session
List devices
GET /cloudphone/automation/envs
Lists the devices within the credential's range: environment ID, name and status.
Permission: env.view (View environments).
data in the response: EnvSummary[].
List nodes
GET /cloudphone/automation/nodes
Lists summaries of the nodes the credential can see.
Scope: observe. Permission: env.view (View environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
providerId | query | integer | No | Only this node |
data in the response: NodeSummary[].
Check the credential
GET /cloudphone/automation/whoami
Returns the credential's user, scopes, device range and the MCP tools this credential can use.
data in the response: WhoAmIResp
Observe
Attestation status
GET /cloudphone/automation/envs/{id}/attestation
Reads the device's attestation status.
Scope: observe. Permission: env.view (View environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response: {attestation: AttestationView}.
Screenshot
GET /cloudphone/automation/envs/{id}/screenshot
Takes a screenshot of the device. With any of max_edge, format, quality or annotate, returns a compressed image with the original resolution and the scale (JPEG with a 1024-pixel long edge by default); without them, returns the older raw screenshot.
Scope: observe. Permission: env.remote.screenshot (Take screenshots).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
max_edge | query | integer | No | Long edge in pixels, 256–2048, default 1024 |
format | query | string | No | jpeg (default) or png |
quality | query | integer | No | JPEG quality, 1–100, default 75 |
annotate | query | boolean | No | When true, marks the element IDs from the latest screen read on the image |
data in the response: ScreenshotView
Automation status
GET /cloudphone/automation/envs/{id}/status
Gets whether the device can be interacted with, its capabilities and its control state. Call it before acting or when an action fails, and use the capabilities to decide which actions are available.
Scope: observe. Permission: env.view (View environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response: StatusView
Read the screen
GET /cloudphone/automation/envs/{id}/ui-tree
Reads the device's current screen. With any of format, scope, under, depth or max, returns a compact snapshot (default) or a structured tree; without them, returns the older raw UI tree. New integrations should pass format.
Scope: observe. Permission: env.remote.screenshot (Take screenshots).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
includeInvisible | query | boolean | No | When true, includes invisible elements |
format | query | string | No | compact (default, compact snapshot) or json (structured tree) |
scope | query | string | No | interactive (default, only elements that can be interacted with or have text) or all (every element) |
under | query | string | No | Only the subtree under this element ID |
depth | query | integer | No | Maximum subtree depth, 1–100 |
max | query | integer | No | Maximum number of element lines to list, 1–2000, default 150 |
data in the response: UITreeView
Find elements
POST /cloudphone/automation/envs/{id}/ui/find
Finds elements on the current screen by text, regex, resource ID, description or class name; all conditions must match. Returns the compact lines of the matches and suggested selectors that are unique on the current screen, or an empty result when nothing matches.
Scope: observe. Permission: env.remote.screenshot (Take screenshots).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIFindInput | Yes | Search conditions |
data in the response: UIFindView
UI actions
Clear an input field
POST /cloudphone/automation/envs/{id}/ui/clear
Clears the focused input field or the one given by selector.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Input method action
POST /cloudphone/automation/envs/{id}/ui/editor
Runs the input method action editorAction on the focused input field (an Android IME action number, such as 2 Go, 3 Search, 4 Send or 6 Done)
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Press a key
POST /cloudphone/automation/envs/{id}/ui/key
Sends the Android key code code (66 Enter, 4 Back, 3 Home, 67 Delete)
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Swipe
POST /cloudphone/automation/envs/{id}/ui/swipe
Swipes from from to to (normalized coordinates, 0..1); durationMs is the swipe duration. Use it to turn pages, scroll lists or pull to refresh.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Tap
POST /cloudphone/automation/envs/{id}/ui/tap
Taps an element. Locate it by element ID (with its snapshot version), resource ID, text or description, and use the normalized coordinates point only when no element is available. A longPressMs greater than 0 long-presses. Taps the platform judges high-risk may be held first and return a confirmation.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Type text
POST /cloudphone/automation/envs/{id}/ui/type
Types text into the focused input field (or the element given by selector). When clear is true the field is cleared first; when submit is true Enter is pressed afterwards. Without the textInput capability, only ASCII can be typed.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Wait for a condition
POST /cloudphone/automation/envs/{id}/ui/wait
Waits for a condition to hold: the element given by selector appears, or until is gone (the element disappears), idle (the screen stays unchanged for idleMs milliseconds), animation (animations end) or package (the app comes to the foreground). Wait for one condition at a time; timeoutMs is the limit, and a timeout returns 1003.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIActionInput | Yes | Action parameters |
data in the response: UIActionResult
Batches, flows and run reports
Run a flow
POST /cloudphone/automation/envs/{id}/flows
Checks a yunyoo.flow/2 flow and runs it as an async task. Returns a task ID; track it with Get task. When the run deviates, the task ends with 53019 and a deviation report.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | FlowRunInput | Yes | Flow and variables |
data in the response: FlowStarted
Batch actions
POST /cloudphone/automation/envs/{id}/ui/batch
Submits several UI and app actions at once and runs them step by step. Steps have the same structure as the yunyoo.flow/2 flow format, up to 50 steps and 60 seconds. By default it stops at the first failure and returns per-step results and where it failed; when a confirmation is needed it returns the confirmation and where to resume (from, at, sub)
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | UIBatchInput | Yes | Steps and variables |
data in the response: FlowView
Check a flow
POST /cloudphone/automation/flows/check
Only checks the format of a flow or a step list, without running it, and returns the number of steps, the variables to pass at run time and the secret placeholder names used.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| body | FlowCheckInput | Yes | Flow or step list |
data in the response: FlowCheckView
List runs
GET /cloudphone/automation/runs
Lists runs, newest first.
Permission: automation.report.view (View automation runs).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
env | query | integer | No | Only this device |
limit | query | integer | No | Maximum number of entries to return |
data in the response: {list: RunView[]}.
Run report
GET /cloudphone/automation/runs/{rid}
Gets the report of a run: each step's tool, parameter summary, target element, effect check, result code and duration.
Permission: automation.report.view (View automation runs).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
rid | path | string | Yes | Run ID |
data in the response: RunView
Generate a flow draft
GET /cloudphone/automation/runs/{rid}/flow
Generates a flow draft from a run record. Only successful actions are kept, and typed text that cannot be copied verbatim becomes a variable INPUT_n.
Permission: automation.report.view (View automation runs).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
rid | path | string | Yes | Run ID |
data in the response: Drafted
Confirmations and handoff
Get a confirmation
GET /cloudphone/automation/confirmations/{cid}
Gets a confirmation's status; with wait, waits up to that many seconds until the status is no longer pending.
Permission: env.view (View environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
cid | path | string | Yes | Confirmation ID |
wait | query | integer | No | Maximum wait in seconds, 0–60 |
data in the response: ConfirmationView
Withdraw a confirmation
POST /cloudphone/automation/confirmations/{cid}/cancel
Withdraws a confirmation that is still pending; resending with it afterwards returns 53011.
Permission: env.view (View environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
cid | path | string | Yes | Confirmation ID |
data in the response: ConfirmationView
Hand off to a person
POST /cloudphone/automation/envs/{id}/handoff
Asks the user to take over this device; reason says why. During the handoff, action endpoints return 53014, and they work again once the user hands back in the viewer. Without reason, only the current control state is returned.
Scope: ui-action. Permission: env.remote.control (Control remotely).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | HandoffReq | No | Handoff reason |
data in the response: ControlView
Apps
App operation
POST /cloudphone/automation/envs/{id}/app-op
Launches, stops, clears, uninstalls or updates an app. Uninstalling and clearing data are high-risk actions and return a confirmation when the user needs to approve.
Scope: app. Permission: any of app.operate (Start and stop apps), app.remove (Uninstall apps), app.install (Install apps).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | AppOpInput | Yes | Operation and package name |
data in the response: RunCommandResult
List apps
GET /cloudphone/automation/envs/{id}/apps
With format=list, returns package names and readable names; without it, returns the older device-side listing. New integrations should pass format=list.
Scope: app. Permission: app.view (Browse apps).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
format | query | string | No | list |
data in the response: AppListView
Install apps
POST /cloudphone/automation/envs/{id}/apps
Installs apps from the app library and returns an install task; track it with Get task.
Scope: app. Permission: app.install (Install apps).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | AppInstallReq | Yes | App IDs in the app library |
data in the response: AgentTask
Files
Fetch a file
POST /cloudphone/automation/envs/{id}/files/pull
Fetches a file from the device and returns a task; once the task finishes, Get task gives a download link valid for 15 minutes.
Scope: file. Permission: env.file.download (Download files).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | FilePullReq | Yes | Path of the file on the device |
data in the response: AgentTask
Push a file
POST /cloudphone/automation/envs/{id}/files/push
Pushes an uploaded file to the device's download folder and returns a push task.
Scope: file. Permission: env.file.upload (Upload files).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | FilePushReq | Yes | The upload session's token |
data in the response: AgentTask
Create an upload session
POST /cloudphone/automation/envs/{id}/files/upload-session
Creates an upload session for a file to push to the device. Upload to the returned URL, then call Push a file with its token.
Scope: file. Permission: env.file.upload (Upload files).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | FileSessionReq | Yes | File name and size |
data in the response: UploadSessionResp
Power and tasks
Pause
POST /cloudphone/automation/envs/{id}/pause
Pauses the environment and keeps its memory state; only for environments on local nodes. Returns a task.
Scope: lifecycle. Permission: env.stop (Stop environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response: {status: string, taskId: integer}.
Reboot
POST /cloudphone/automation/envs/{id}/reboot
Reboots the device in the background.
Scope: lifecycle. Permission: env.start (Start environments), env.stop (Stop environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response is empty.
Resume
POST /cloudphone/automation/envs/{id}/resume
Resumes a paused environment and returns a task.
Scope: lifecycle. Permission: env.start (Start environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response: {status: string, taskId: integer}.
Start
POST /cloudphone/automation/envs/{id}/start
Starts the environment in the background.
Scope: lifecycle. Permission: env.start (Start environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response is empty.
Shut down
POST /cloudphone/automation/envs/{id}/stop
Shuts down in the background.
Scope: lifecycle. Permission: env.stop (Stop environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response is empty.
Sync to the cloud
POST /cloudphone/automation/envs/{id}/sync
Syncs the data of an environment on a local node to the cloud.
Scope: lifecycle. Permission: env.sync (Sync to cloud).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | EnvSyncReq | No | Sync settings |
data in the response is empty.
Get task
GET /cloudphone/automation/tasks/{id}
Gets the status and result of an async task (power, backups, file transfers, app installs, flows). The scope needed depends on the task type. When a file fetch has finished and you have the file download permission, a download link valid for 15 minutes is included.
Permission: env.view (View environments).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Task ID |
data in the response: TaskView
Backups and portable packages
List backups
GET /cloudphone/automation/backups
Lists the backups of one device.
Scope: backup. Permission: env.backup.view (View backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
env | query | integer | Yes | Environment ID |
kind | query | string | No | Only backups of this type |
data in the response: {list: EnvBackup[]}.
Package a backup
POST /cloudphone/automation/backups/{id}/package
Packages a backup as a portable package and returns the package ID and the packaging task.
Scope: backup. Permission: env.backup.export (Export backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Backup ID |
| body | PackageCreateReq | Yes | Packaging settings |
data in the response: PackageCreateResult
Restore an app backup
POST /cloudphone/automation/backups/{id}/restore-app
Restores the app from an app backup right away and returns a task. This is a high-risk action and returns a confirmation when the user needs to approve.
Scope: backup. Permission: env.backup.restore (Restore backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Backup ID |
| body | AppRestoreReq | No | Restore settings |
data in the response: {taskId: integer}.
Create a full backup
POST /cloudphone/automation/envs/{id}/backups
Creates a full backup of the device.
Scope: backup. Permission: env.backup.create (Create backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | BackupCreateReq | Yes | Backup settings |
data in the response: EnvBackup
Create an app backup
POST /cloudphone/automation/envs/{id}/backups/app
Backs up only one app's data.
Scope: backup. Permission: env.backup.create (Create backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | AppBackupCreateReq | Yes | App and backup settings |
data in the response: EnvBackup
Set the backup to restore
POST /cloudphone/automation/envs/{id}/restore
Sets a full backup to be restored at the next start; an empty backupId cancels it. This is a high-risk action and returns a confirmation when the user needs to approve.
Scope: backup. Permission: env.backup.restore (Restore backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | RestoreSetReq | Yes | The backup to restore |
data in the response is empty.
Get a package
GET /cloudphone/automation/packages/{pid}
Gets a portable package's details and shares.
Scope: backup. Permission: env.backup.view (View backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
pid | path | string | Yes | Package ID |
data in the response: PackageDetail
Download a package
GET /cloudphone/automation/packages/{pid}/download
Redirects with 302 to the package's presigned download URL.
Scope: backup. Permission: env.backup.export (Export backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
pid | path | string | Yes | Package ID |
Returns HTTP 302, Redirects to the download URL.
Share a backup package
POST /cloudphone/automation/packages/{pid}/shares
Creates a share link for the package; the token is returned only this once. Returns a confirmation when the user needs to approve.
Scope: backup. Permission: env.backup.share (Share backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
pid | path | string | Yes | Package ID |
| body | ShareCreateReq | No | Validity and download limit |
data in the response: ShareCreateResult
Import a package
POST /cloudphone/automation/packages/import
Imports a package as a restore, a data environment, an app, a profile or a new environment. The target environment must be within the credential's range. When dryRun is true, only the import plan is returned.
Scope: backup. Permission: env.backup.import (Import backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| body | PackageImportReq | Yes | Import target and settings |
data in the response: PackageImportResult
Inspect an uploaded package
POST /cloudphone/automation/packages/inspect
Reads an uploaded package's metadata; use it to check the contents before importing.
Scope: backup. Permission: env.backup.import (Import backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| body | PackageInspectReq | Yes | Upload session |
data in the response: PackageDetail
Create a package upload session
POST /cloudphone/automation/packages/upload-session
Creates an upload session for a package you are going to import.
Scope: backup. Permission: env.backup.import (Import backups).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| body | PackageUploadReq | Yes | File name and size |
data in the response: packageUploadSession
Multi-device batches
Batch action on multiple devices
POST /cloudphone/automation/batch
Runs the same UI action, app operation or command on the devices selected by a group, a tag or a list, and returns a result for each; one device failing does not affect the others. The scope needed depends on kind.
Permission: .
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| body | BatchInput | Yes | Selector and action |
data in the response: BatchItemResult[].
Escape hatches
Local bridge
POST /cloudphone/automation/envs/{id}/connect
Sets up a local bridge session. This is an escape hatch that needs the local-bridge scope, which is not granted by default; once set up, connect the data plane through tunnel.
Scope: local-bridge. Permission: env.adb.connect (ADB connection).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
data in the response: ConnectResp
Run a command
POST /cloudphone/automation/envs/{id}/run-command
Runs a command on the device. This is an escape hatch that needs the run-command scope, which is not granted by default; use it only when the UI and app endpoints cannot do the job.
Scope: run-command. Permission: env.shell (Terminal and commands).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
| body | RunCommandInput | Yes | Command and arguments |
data in the response: RunCommandView
Bridge data plane
GET /cloudphone/automation/envs/{id}/tunnel
After upgrading to WebSocket, relays the bridge's byte stream in both directions.
Scope: local-bridge. Permission: env.adb.connect (ADB connection).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | Yes | Environment ID |
Returns HTTP 101, Upgraded to WebSocket.
Data types
These are the data types used in request bodies and responses, sorted by name.
AgentTask
| Field | Type | Required | Description |
|---|---|---|---|
ID | integer | No | Primary key |
backupId | integer | No | |
createdAt | string | No | Creation time |
detail | string | No | |
envId | integer | No | |
errorCode | string | No | |
expiresAt | string | No | |
message | string | No | |
parentId | integer | No | |
percent | integer | No | |
providerId | integer | No | |
sessionId | integer | No | |
stage | string | No | |
status | string | No | |
type | string | No | |
updatedAt | string | No | Update time |
AppBackupCreateReq
| Field | Type | Required | Description |
|---|---|---|---|
includeObb | boolean | No | Also back up the app's OBB data |
package | string | Yes | App package name |
target | string | No | Where to keep it: cloud (default) or local (only on the local node where the environment runs) |
AppInstallReq
| Field | Type | Required | Description |
|---|---|---|---|
appIds | integer[] | Yes | App IDs in the app library |
AppItem
| Field | Type | Required | Description |
|---|---|---|---|
label | string | No | Readable name |
package | string | No | Package name |
versionName | string | No | Version name |
AppListView
| Field | Type | Required | Description |
|---|---|---|---|
apps | AppItem[] | No | Installed apps |
device | string | No | The device, written as env:<environment ID> |
note | string | No | A note when the list comes from the device instead |
source | string | No | Where the list comes from: platform (the platform's list) or device (listed on the device) |
AppOpInput
| Field | Type | Required | Description |
|---|---|---|---|
activity | string | No | The activity to launch |
keepData | boolean | No | Keep the data when uninstalling |
op | string | Yes | Operation: launch, stop, clear, uninstall or update |
package | string | Yes | App package name |
AppRestoreReq
| Field | Type | Required | Description |
|---|---|---|---|
ignoreVersion | boolean | No | Restore even if the app version differs from the backup |
AttestationView
| Field | Type | Required | Description |
|---|---|---|---|
check | AttestCheckView | No | |
delivery | string | No | |
enrollmentStatus | string | No | |
keyboxFingerprint | string | No | |
keyboxRef | integer | No | |
keyboxStatus | string | No | |
leaseStatus | string | No | |
locked | boolean | No | |
mode | string | No | |
runtimeMode | string | No | |
source | string | No | |
strongIntegrity | boolean | No | |
supply | string | No | |
trust | string | No |
AttestCheckView
| Field | Type | Required | Description |
|---|---|---|---|
checkedAt | string | No | |
failed | string | No | |
keyboxMatch | boolean | No | |
rootKind | string | No | |
state | string | No |
AttestSource
| Field | Type | Required | Description |
|---|---|---|---|
keyboxId | integer | No | The keybox ID, when kind is user |
kind | string | No | pool (the platform, default) or user (your own keybox) |
automation.Bounds
| Field | Type | Required | Description |
|---|---|---|---|
bottom | number | No | |
left | number | No | |
right | number | No | |
top | number | No |
automation.Selector
| Field | Type | Required | Description |
|---|---|---|---|
class | string | No | Class name |
desc | string | No | Description |
id | string | No | Resource ID |
index | integer | No | Index among several elements matching the same condition, from 0 |
text | string | No | Text equals |
textContains | string | No | Text contains |
textRegex | string | No | Regex the text matches |
BackupCreateReq
| Field | Type | Required | Description |
|---|---|---|---|
dataEnvId | integer | No | The data environment to back up; defaults to the one in use |
ignoreWindow | boolean | No | On a local Linux node, run right away instead of waiting for the backup window |
kind | string | No | Backup type: full (default) or incremental |
name | string | No | Backup name |
parentBackupId | integer | No | The backup an incremental backup is based on |
target | string | No | Where to keep it: cloud (default) or local (only on the local node where the environment runs) |
BackupShare
| Field | Type | Required | Description |
|---|---|---|---|
ID | integer | No | Primary key |
createdAt | string | No | Creation time |
createdBy | integer | No | |
downloadCount | integer | No | |
expiresAt | string | No | |
lastDownloadAt | string | No | |
maxDownloads | integer | No | |
packageId | integer | No | |
requireLogin | boolean | No | |
revokedAt | string | No | |
updatedAt | string | No | Update time |
BatchInput
| Field | Type | Required | Description |
|---|---|---|---|
appOp | AppOpInput | No | The app operation, when kind is app-op |
command | RunCommandInput | No | The command, when kind is run-command |
kind | string | Yes | Action type: ui-action, app-op or run-command |
selector | SelectorSpec | No | The selected devices |
uiAction | UIActionInput | No | The UI action, when kind is ui-action |
BatchItemResult
| Field | Type | Required | Description |
|---|---|---|---|
envId | integer | No | Environment ID |
error | string | No | Why it failed |
ok | boolean | No | Whether this device succeeded |
result | any | No | This device's result, with the same structure as the single-device endpoint |
Candidate
| Field | Type | Required | Description |
|---|---|---|---|
line | string | No | The element's compact line |
ref | string | No | Element ID |
score | number | No | |
selectors | automation.Selector[] | No | Suggested selectors that are unique on the current screen |
ConfirmationView
| Field | Type | Required | Description |
|---|---|---|---|
action | string | No | The held action |
categories | string[] | No | Risk categories |
clientName | string | No | The requester's client |
createdAt | string | No | Creation time |
decidedAt | string | No | When it was decided |
envId | integer | No | Environment ID |
executedAt | string | No | When it ran |
expiresAt | string | No | Expiry time |
id | string | No | Confirmation ID |
intent | string | No | The intent stated by the caller |
skillName | string | No | The requester's Skill |
status | string | No | pending, approved, denied, expired, cancelled or executed |
summary | string | No | Action summary |
thumb | string | No | Screenshot taken before the action |
tokenKind | string | No | Type of the requester's credential |
tokenName | string | No | Name of the requester's credential |
url | string | No | Confirmation page URL |
ConnectResp
| Field | Type | Required | Description |
|---|---|---|---|
expiresAt | string | No | Expiry time |
hint | string | No | How to use it |
sessionId | string | No | Bridge session ID |
ControlView
| Field | Type | Required | Description |
|---|---|---|---|
byYou | boolean | No | Whether the current user took over |
enabled | boolean | No | Whether human takeover is turned on |
envId | integer | No | Environment ID |
lastActionAt | string | No | Time of the latest automation action |
reason | string | No | Handoff reason |
since | string | No | When it entered the current state |
state | string | No | Control state: free, automating, human or waiting-human |
url | string | No | Viewer URL |
Deviation
| Field | Type | Required | Description |
|---|---|---|---|
candidates | Candidate[] | No | |
command | string | No | |
expect | Identity | No | |
foreground | string | No | |
found | Hit | No | |
path | string | No | |
reason | string | No | |
resume | integer | No | |
screen | string | No | |
selector | flow.Selector | No | |
step | integer | No |
Drafted
| Field | Type | Required | Description |
|---|---|---|---|
flow | a yunyoo.flow/2 flow | No | The generated flow |
skipped | integer | No | Number of steps left out of the draft |
vars | string[] | No | Variables to pass at run time, for input that could not be copied verbatim |
EnvBackup
| Field | Type | Required | Description |
|---|---|---|---|
ID | integer | No | Primary key |
actorUserId | integer | No | |
androidVersion | string | No | |
appPackage | string | No | |
appVersionCode | integer | No | |
boundPackage | string | No | |
chainDepth | integer | No | |
createdAt | string | No | Creation time |
dataEnvId | integer | No | |
deviceProfile | string | No | |
envId | integer | No | |
errorCode | string | No | |
expiresAt | string | No | |
format | integer | No | |
hasRuntimeState | boolean | No | |
hasSecureState | boolean | No | |
identityMatch | boolean | No | |
importPackageId | integer | No | |
kind | string | No | |
location | string | No | |
name | string | No | |
nodeId | integer | No | |
parentBackupId | integer | No | |
plainSize | integer | No | |
purpose | string | No | |
remark | string | No | |
retryCount | integer | No | |
rootVariant | string | No | |
scheduledAt | string | No | |
source | string | No | |
status | string | No | |
updatedAt | string | No | Update time |
usedBytes | integer | No |
EnvScopeSpec
| Field | Type | Required | Description |
|---|---|---|---|
envIds | integer[] | No | The environments, when kind is env |
groupIds | integer[] | No | The groups, when kind is group |
kind | string | No | Range: all, group or env |
EnvSummary
| Field | Type | Required | Description |
|---|---|---|---|
groupId | integer | No | Group ID |
id | integer | No | Environment ID |
status | string | No | Status |
title | string | No | Name |
EnvSyncReq
| Field | Type | Required | Description |
|---|---|---|---|
stopAndSync | boolean | No | When true, shuts down first and then syncs |
FilePullReq
| Field | Type | Required | Description |
|---|---|---|---|
path | string | Yes | Path of the file on the device |
FilePushReq
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | The token returned by the upload session |
FileSessionReq
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | File name |
size | integer | Yes | File size in bytes |
flow.Selector
| Field | Type | Required | Description |
|---|---|---|---|
class | string | No | Class name |
desc | string | No | Description |
id | string | No | Resource ID |
index | integer | No | Index among several elements matching the same condition, from 0 |
point | Point | No | Fallback coordinates when the element cannot be found, as a fraction of the screen width and height |
text | string | No | Text equals |
textContains | string | No | Text contains |
textRegex | string | No | Regex the text matches |
FlowCheckInput
| Field | Type | Required | Description |
|---|---|---|---|
flow | object | No | The flow to check; give either this or steps |
steps | object[] | No | The step list to check |
vars | object | No | Known variable values |
FlowCheckView
| Field | Type | Required | Description |
|---|---|---|---|
secrets | string[] | No | Secret placeholder names used; the caller supplies the values on its own computer |
steps | integer | No | Number of steps |
vars | string[] | No | Variables to pass at run time |
FlowRunInput
| Field | Type | Required | Description |
|---|---|---|---|
at | string | No | The step position returned when the run paused |
confirmation | string | No | ID of an approved confirmation; resume with the pause returned when the run paused |
flow | object | No | Content of the yunyoo.flow/2 flow |
from | integer | No | Top-level step to resume from, starting at 1 |
secrets | object | No | Values for secret placeholders, kept only in memory until the run ends |
sub | integer | No | The controlled action number returned when the run paused |
vars | object | No | Variable values |
FlowStarted
| Field | Type | Required | Description |
|---|---|---|---|
runId | string | No | Run ID |
steps | integer | No | Number of steps |
taskId | integer | No | Task ID; track it with Get task |
FlowView
| Field | Type | Required | Description |
|---|---|---|---|
code | integer | No | Error code when it did not pass |
confirmation | ConfirmationView | No | The confirmation waiting for approval |
deviation | Deviation | No | Deviation report: step position, expected element, a summary of the current screen and similar elements |
failed | StepResult | No | The first failed step |
inspect | string | No | Compact snapshot at the end |
message | string | No | Why it did not pass |
pause | Pause | No | Where it paused for a confirmation; pass it when resuming |
resume | integer | No | Step to resume from, starting at 1; 0 means from the beginning |
runId | string | No | Run ID |
status | string | No | passed, failed, deviated, paused, cancelled or limited |
steps | StepResult[] | No | Per-step results |
HandoffReq
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | No | Why you are handing off, shown to the user who takes over; when empty, only the current control state is returned |
Hit
| Field | Type | Required | Description |
|---|---|---|---|
line | string | No | The element's compact line |
ref | string | No | Element ID |
selectors | automation.Selector[] | No | Suggested selectors that are unique on the current screen |
Identity
| Field | Type | Required | Description |
|---|---|---|---|
class | string | No | |
desc | string | No | |
id | string | No | |
text | string | No |
ImportEnvSpec
| Field | Type | Required | Description |
|---|---|---|---|
attestationSource | AttestSource | No | Attestation source; defaults to the platform |
bindAck | boolean | No | Confirms that after switching to a bound app, third-party apps other than the bound app will be disabled |
bindAppId | integer | No | The bound app; defaults to the package's source |
dataGib | integer | No | Disk size (GiB) |
deviceId | integer | No | Slot on the local node |
deviceSource | string | No | Device source: owned (a purchased device) or temporary (a temporary device) |
egressConfirm | string | No | Egress confirmation token returned by the check, used when the proxy and the package's anchor need confirming |
groupId | integer | No | Group |
proxyId | integer | No | Proxy |
remark | string | No | Remark |
skuId | integer | No | Plan ID |
tagIds | integer[] | No | Tags |
title | string | No | Name |
ImportPlan
| Field | Type | Required | Description |
|---|---|---|---|
anchor | object | No | The egress anchor in the package |
attestation | string | No | Attestation source |
bindAck | boolean | No | The target environment has a bound app but the package's source did not; the real import must include bindAck |
boundPackage | string | No | The bound app's package name carried over when creating an environment from the package; empty when the source was not bound |
confirmToken | string | No | Confirmation token when the egress needs confirming; pass it as egressConfirm for the real import |
deviceProfile | string | No | The device model the package is for |
format | integer | No | Package format version |
hasSeed | boolean | No | Whether the package contains a device identity seed |
identity | string | No | How the identity will be handled |
identityPublic | object | No | Public values derived from the device identity in the package, redacted |
kind | string | No | Package type |
mode | string | No | Import mode |
proxyGrade | string | No | How well the proxy matches the anchor |
rootVariant | string | No | The variant the package is for |
runtimeState | boolean | No | Whether the runtime state will be restored |
secureState | boolean | No | Whether the secure state will be restored |
skuName | string | No | Plan name of the new environment |
title | string | No | Name of the new environment |
verify | boolean | No | The real import must include your account password for re-verification |
ImportTarget
| Field | Type | Required | Description |
|---|---|---|---|
env | ImportEnvSpec | No | Settings for the new environment, when mode is env |
envId | integer | No | Target environment; leave it out when mode is env |
mode | string | Yes | Import mode: restore, data-env, app, profile or env (create a new environment) |
Node
| Field | Type | Required | Description |
|---|---|---|---|
bounds | automation.Bounds | No | The element's bounds on screen (pixels) |
checkable | boolean | No | |
checked | boolean | No | |
children | Node[] | No | Child elements |
className | string | No | Class name |
clickable | boolean | No | |
contentDesc | string | No | Description |
editable | boolean | No | |
elementId | string | No | Stable element ID |
enabled | boolean | No | |
focusable | boolean | No | |
focused | boolean | No | |
longClickable | boolean | No | |
package | string | No | Package name of the app it belongs to |
password | boolean | No | Whether it is a password field; password fields return no text |
ref | string | No | Element ID |
resourceId | string | No | Resource ID |
scrollable | boolean | No | |
selected | boolean | No | |
text | string | No | Text |
NodeDoctor
| Field | Type | Required | Description |
|---|---|---|---|
failed | string[] | No | Checks that did not pass |
ok | boolean | No | Whether the health check passed |
NodeSlots
| Field | Type | Required | Description |
|---|---|---|---|
total | integer | No | Total slots |
used | integer | No | Slots in use |
NodeSummary
| Field | Type | Required | Description |
|---|---|---|---|
doctor | NodeDoctor | No | The local node's health check result |
execMode | string | No | How the local node runs |
lastSeenAt | string | No | When it was last online |
name | string | No | Name |
nodeType | string | No | Node type |
online | boolean | No | Whether it is online |
platform | string | No | The local node's operating system |
providerId | integer | No | Node ID |
scope | string | No | cloud (cloud node) or local (local node) |
slots | NodeSlots | No | Slot usage |
NormPoint
| Field | Type | Required | Description |
|---|---|---|---|
x | number | No | Horizontal coordinate as a fraction of the screen width, 0–1 |
y | number | No | Vertical coordinate as a fraction of the screen height, 0–1 |
PackageCreateReq
| Field | Type | Required | Description |
|---|---|---|---|
escrow | boolean | No | For older passphrase packages, escrow the member keys so the passphrase can be recovered; paying users only |
identityTransfer | boolean | No | Agree to transfer the device identity in the package to whoever imports it |
includeSecureState | boolean | No | Whether to include the secure state; full packages include it by default |
includeSeed | boolean | No | Whether to include the device identity seed |
kdf | PackageKDF | No | Parameters used to derive wrapKeyB64 |
password | string | No | Account password, checked when the device identity is included |
wrapKeyB64 | string | No | Wrapping key for older passphrase packages (base64), derived from the passphrase on this computer; not needed when the platform has sealed export turned on |
PackageCreateResult
| Field | Type | Required | Description |
|---|---|---|---|
fileName | string | No | Package file name |
packageId | string | No | Package ID |
taskId | integer | No | Packaging task ID |
PackageDetail
| Field | Type | Required | Description |
|---|---|---|---|
ID | integer | No | Primary key |
actorUserId | integer | No | |
androidVersion | string | No | |
appPackage | string | No | |
backupId | integer | No | |
createdAt | string | No | Creation time |
deviceProfile | string | No | |
downloadCount | integer | No | |
envId | integer | No | |
envSegment | boolean | No | |
errorCode | string | No | |
errorMsg | string | No | |
escrow | boolean | No | |
expiresAt | string | No | |
fileName | string | No | |
format | integer | No | |
hasRuntimeState | boolean | No | |
hasSecureState | boolean | No | |
hasSeed | boolean | No | |
identityTransfer | boolean | No | |
kdf | PackageKDF | No | |
keyId | string | No | |
kind | string | No | |
originShareId | integer | No | |
packageId | string | No | |
rewrapCount | integer | No | |
rootVariant | string | No | |
shares | BackupShare[] | No | |
sizeBytes | integer | No | |
source | string | No | |
status | string | No | |
taskId | integer | No | |
updatedAt | string | No | Update time |
PackageImportReq
| Field | Type | Required | Description |
|---|---|---|---|
bindAck | boolean | No | Confirms the import when the target environment has a bound app but the package's source did not; third-party apps other than the bound app will be disabled |
dataEnvName | string | No | Name to use when importing as a data environment |
dryRun | boolean | No | When true, only returns the import plan and does not create a task |
fileName | string | No | Name of the uploaded file |
identityMode | string | No | How the identity is handled when importing as a profile: template (take the settings only, keep the identity) or transfer (take over the identity in the package) |
identityTransfer | boolean | No | Must be true when a machine credential takes over the identity in the package |
ignoreVersion | boolean | No | Import even if the versions differ |
packageId | string | No | An existing package ID; give either this or uploadSessionId |
password | string | No | Account password, for re-verifying a sensitive action |
restoreIdentity | boolean | No | Whether to take over the device identity in the package; defaults to true |
target | ImportTarget | Yes | Import target |
uploadSessionId | string | No | Upload session ID |
wrapKeyB64 | string | No | Wrapping key for older passphrase packages, derived on this computer using the kdf from the inspection result; not needed for packages sealed by the platform |
PackageImportResult
| Field | Type | Required | Description |
|---|---|---|---|
packageId | string | No | Package ID |
plan | ImportPlan | No | The import plan, when dryRun is set |
taskId | integer | No | Import task ID; empty with dryRun |
PackageInspectReq
| Field | Type | Required | Description |
|---|---|---|---|
fileName | string | No | Package file name |
uploadSessionId | string | Yes | Upload session ID |
PackageKDF
| Field | Type | Required | Description |
|---|---|---|---|
iterations | integer | No | Iteration count |
saltB64 | string | No | Salt (base64) |
PackageUploadReq
| Field | Type | Required | Description |
|---|---|---|---|
fileName | string | Yes | Package file name, with the .wp extension |
size | integer | Yes | Package size in bytes |
packageUploadSession
| Field | Type | Required | Description |
|---|---|---|---|
headers | object | No | Headers to send with the upload |
mode | string | No | Upload method |
partSize | integer | No | Part size (bytes) |
parts | UploadPartURL[] | No | Upload URLs for each part |
uploadSessionId | string | No | Upload session ID |
url | string | No | URL for uploading the whole file at once |
Pause
| Field | Type | Required | Description |
|---|---|---|---|
confirmation | string | No | ID of the confirmation waiting for approval |
path | string | No | Position of the paused step |
step | integer | No | Top-level step number where it paused |
sub | integer | No | Which controlled action within this step, from 0 |
Point
| Field | Type | Required | Description |
|---|---|---|---|
x | number | No | |
y | number | No |
provider.Bounds
| Field | Type | Required | Description |
|---|---|---|---|
bottom | number | No | |
left | number | No | |
right | number | No | |
top | number | No |
RefCandidate
| Field | Type | Required | Description |
|---|---|---|---|
bounds | provider.Bounds | No | |
className | string | No | |
contentDesc | string | No | |
ref | string | No | |
resourceId | string | No | |
text | string | No |
RestoreSetReq
| Field | Type | Required | Description |
|---|---|---|---|
backupId | integer | No | The full backup to restore; when empty, the pending restore is cancelled |
bindAck | boolean | No | Confirms the restore when the target environment has a bound app but the backup's source did not; third-party apps other than the bound app will be disabled |
password | string | No | Account password, for re-verifying a sensitive action |
RunCommandInput
| Field | Type | Required | Description |
|---|---|---|---|
argv | string[] | Yes | Command and arguments |
cwd | string | No | Working directory |
env | object | No | Extra environment variables |
mode | string | No | sync (default, waits for the result) or async (returns a task right away) |
shell | boolean | No | When true, the command is interpreted by the shell |
timeoutMs | integer | No | Timeout in milliseconds |
RunCommandResult
| Field | Type | Required | Description |
|---|---|---|---|
channel | string | No | Execution channel |
duration_ms | integer | No | Duration in milliseconds |
exit_code | integer | No | Exit code |
invoke_id | string | No | Call ID |
output_bytes | integer | No | Output size in bytes |
status | string | No | succeeded, failed or timed_out |
stderr | string | No | Standard error |
stderr_truncated | boolean | No | Whether standard error was truncated |
stdout | string | No | Standard output |
stdout_truncated | boolean | No | Whether standard output was truncated |
RunCommandView
| Field | Type | Required | Description |
|---|---|---|---|
channel | string | No | Execution channel |
durationMs | integer | No | Duration in milliseconds |
exitCode | integer | No | Exit code |
invokeId | string | No | Call ID |
outputBytes | integer | No | Output size in bytes |
outputUrl | string | No | Download URL for output that was too large to return |
status | string | No | succeeded, failed, timed_out or accepted (async request accepted) |
stderr | string | No | Standard error |
stderrTruncated | boolean | No | Whether standard error was truncated |
stdout | string | No | Standard output |
stdoutTruncated | boolean | No | Whether standard output was truncated |
taskId | integer | No | The task ID, when mode is async; track it with Get task |
RunView
| Field | Type | Required | Description |
|---|---|---|---|
clientName | string | No | Client |
endedAt | string | No | End time |
entry | string | No | Entry point |
envId | integer | No | Environment ID |
failedSteps | integer | No | Number of failed steps |
id | string | No | Run ID |
items | StepView[] | No | Per-step records |
skillName | string | No | Skill |
startedAt | string | No | Start time |
status | string | No | Run result |
steps | integer | No | Number of steps |
tokenKind | string | No | Credential type |
tokenName | string | No | Credential name |
ScreenshotView
| Field | Type | Required | Description |
|---|---|---|---|
annotated | boolean | No | Whether element IDs are marked |
format | string | No | jpeg or png |
height | integer | No | Image height |
image_base64 | string | No | Image content (base64) |
notes | string[] | No | Processing notes |
scale | number | No | The image's scale relative to the original resolution |
snapshot | integer | No | Snapshot version used for the marks |
source_height | integer | No | Original screen height |
source_width | integer | No | Original screen width |
width | integer | No | Image width |
SelectorSpec
| Field | Type | Required | Description |
|---|---|---|---|
envIds | integer[] | No | Selects these environments |
groupId | integer | No | Selects the devices in this group |
tagId | integer | No | Selects the devices with this tag |
ShareCreateReq
| Field | Type | Required | Description |
|---|---|---|---|
expiresInHours | integer | No | Hours it stays valid |
identityTransfer | boolean | No | Agree that the device identity in the package moves with the share; must be true for packages with a device identity |
maxDownloads | integer | No | Maximum number of downloads |
requireLogin | boolean | No | No longer used; claiming always requires signing in |
ShareCreateResult
| Field | Type | Required | Description |
|---|---|---|---|
expiresAt | string | No | Expiry time |
shareId | integer | No | Share ID |
shareUrl | string | No | Share link; claiming requires signing in |
token | string | No | Share token, returned only this once |
StatusView
| Field | Type | Required | Description |
|---|---|---|---|
capabilities | string[] | No | Capabilities, such as textInput and refIdentity |
control | string | No | Control state: free, automating, human or waiting-human |
degraded | boolean | No | Whether this is the degraded tier |
interactable | boolean | No | Whether the device can be interacted with now |
protocol | string | No | Automation protocol version |
StepResult
| Field | Type | Required | Description |
|---|---|---|---|
code | integer | No | Error code |
command | string | No | Step command |
durationMs | integer | No | Duration in milliseconds |
effect | string | No | Effect check |
label | string | No | Step label |
message | string | No | Why it failed |
ok | boolean | No | Whether it succeeded |
path | string | No | Step position, such as steps[3] |
skipped | boolean | No | Whether it was skipped |
step | integer | No | Top-level step number, starting at 1 |
StepView
| Field | Type | Required | Description |
|---|---|---|---|
at | string | No | Time |
code | integer | No | Result code |
confirmation | string | No | The related confirmation |
durationMs | integer | No | Duration in milliseconds |
effect | string | No | Effect check |
entry | string | No | Entry point |
identity | string | No | The target element's identity |
intent | string | No | The intent stated by the caller |
params | string | No | Parameter summary |
seq | integer | No | Step number |
target | string | No | Target element |
thumb | string | No | Screenshot taken after the action |
tool | string | No | Tool |
trace | string | No | Trace ID |
TaskView
| Field | Type | Required | Description |
|---|---|---|---|
ID | integer | No | Primary key |
backupId | integer | No | |
createdAt | string | No | Creation time |
detail | string | No | |
envId | integer | No | |
errorCode | string | No | |
expiresAt | string | No | |
message | string | No | |
parentId | integer | No | |
percent | integer | No | |
providerId | integer | No | |
result | object | No | Task result; for flows, the run report |
sessionId | integer | No | |
stage | string | No | |
status | string | No | |
type | string | No | |
updatedAt | string | No | Update time |
UIActionInput
| Field | Type | Required | Description |
|---|---|---|---|
action | string | No | Action name. For single-device action endpoints the path decides it, so it can be left out; required for multi-device batches: tap, swipe, type or key |
activity | string | No | When until is package, the activity that must also be in front |
clear | boolean | No | When true, clears the input field first |
code | integer | No | Android key code |
durationMs | integer | No | Swipe duration in milliseconds |
editorAction | integer | No | Input method action number |
from | NormPoint | No | Where the swipe starts, in normalized coordinates |
idleMs | integer | No | When until is idle, how many milliseconds the screen must stay unchanged |
longPressMs | integer | No | When greater than 0, long-presses for this many milliseconds |
package | string | No | When until is package, the package name of the app to wait for in the foreground |
point | NormPoint | No | Normalized coordinates, used instead of selector when no element is available |
selector | object | No | Element selector: {"by":"element","id":"e12","snapshot":7} (an element ID with its snapshot version), {"by":"resourceId","value":"…"}, {"by":"text","value":"…"}, {"by":"contentDesc","value":"…"} or {"by":"point","point":{"x":0.5,"y":0.5}} |
submit | boolean | No | When true, presses Enter after typing |
text | string | No | The text to type |
timeoutMs | integer | No | Wait limit in milliseconds |
to | NormPoint | No | Where the swipe ends, in normalized coordinates |
until | string | No | Wait condition: gone, idle, animation or package; when empty, waits for the element given by selector to appear |
verify | boolean | No | When true, waits for the screen to settle and then checks whether the action took effect |
UIActionResult
| Field | Type | Required | Description |
|---|---|---|---|
activity | string | No | Foreground activity after the action |
candidates | RefCandidate[] | No | Candidate elements when the target is not unique |
effect | string | No | Effect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked |
error_code | integer | No | Error code when it did not complete |
matched | boolean | No | Whether the wait found its target |
message | string | No | Why it did not complete |
ok | boolean | No | Whether the action completed |
package | string | No | Package name of the foreground app after the action |
snapshot | object | No | The UI structure some environments attach after the action |
snapshot_version | integer | No | Snapshot version after the action |
target | RefCandidate | No | The element actually acted on |
timed_out | boolean | No | Whether the wait timed out |
UIBatchInput
| Field | Type | Required | Description |
|---|---|---|---|
at | string | No | The step position returned when the run paused |
confirmation | string | No | ID of an approved confirmation; resume with the pause returned when the run paused |
from | integer | No | Top-level step to resume from, starting at 1 |
inspectAtEnd | boolean | No | When true, attaches a compact snapshot taken at the end to the result |
keepGoing | boolean | No | When true, keeps going after a step fails |
secrets | object | No | Values for secret placeholders, kept only in memory until the run ends |
steps | object[] | No | Step list, with the same structure as steps in a yunyoo.flow/2 flow |
sub | integer | No | The controlled action number returned when the run paused |
vars | object | No | Variable values |
UIFindInput
| Field | Type | Required | Description |
|---|---|---|---|
all | boolean | No | When true, also searches off-screen and invisible elements |
class | string | No | Class name; the last segment alone is enough |
desc | string | No | Description contains this text, case-insensitive |
id | string | No | Resource ID; the package prefix can be left out |
max | integer | No | Maximum number of matches to return |
regex | string | No | Text or description matches this regex |
text | string | No | Text contains this, case-insensitive |
UIFindView
| Field | Type | Required | Description |
|---|---|---|---|
device | string | No | The device, written as env:<environment ID> |
hits | Hit[] | No | The matched elements, up to max |
snapshot | integer | No | Snapshot version |
text | string | No | Compact lines of the matched elements, one per line |
total | integer | No | Total number of matches |
UITreeView
| Field | Type | Required | Description |
|---|---|---|---|
activity | string | No | Foreground activity |
capabilities | string[] | No | Capabilities, such as textInput and refIdentity |
degraded | boolean | No | Whether this is the degraded tier |
device | string | No | The device, written as env:<environment ID> |
format | string | No | compact or json |
height | integer | No | Screen height (pixels) |
package | string | No | Package name of the foreground app |
protocol | string | No | Automation protocol version |
root | Node | No | The UI tree, when format is json |
snapshot | integer | No | Snapshot version; include it when acting by element ID |
text | string | No | The compact snapshot, when format is compact |
width | integer | No | Screen width (pixels) |
UploadPartURL
| Field | Type | Required | Description |
|---|---|---|---|
partNumber | integer | No | |
url | string | No |
UploadSessionResp
| Field | Type | Required | Description |
|---|---|---|---|
headers | object | No | Headers to send with the upload |
token | string | No | The token to use when pushing the file |
url | string | No | Upload URL; PUT the file content to it |
WhoAmIResp
| Field | Type | Required | Description |
|---|---|---|---|
apps | string[] | No | Package names of the apps the delegated token may operate |
dialogs | string[] | No | Package names of system dialogs that stay allowed besides the listed apps |
envScope | EnvScopeSpec | No | The devices the credential may operate |
scopes | string[] | No | The credential's scopes |
sealedPackage | boolean | No | When true, newly exported packages are sealed by the platform and packaging needs no passphrase |
tokenId | integer | No | Credential ID |
tools | string[] | No | The MCP tools this credential can use, in tool-list order |
uid | string | No | User number |
userId | integer | No | User ID |
