yunyoo

Documentation

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).

ParameterInTypeRequiredDescription
providerIdqueryintegerNoOnly 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
max_edgequeryintegerNoLong edge in pixels, 256–2048, default 1024
formatquerystringNojpeg (default) or png
qualityqueryintegerNoJPEG quality, 1–100, default 75
annotatequerybooleanNoWhen 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
includeInvisiblequerybooleanNoWhen true, includes invisible elements
formatquerystringNocompact (default, compact snapshot) or json (structured tree)
scopequerystringNointeractive (default, only elements that can be interacted with or have text) or all (every element)
underquerystringNoOnly the subtree under this element ID
depthqueryintegerNoMaximum subtree depth, 1–100
maxqueryintegerNoMaximum 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIFindInputYesSearch 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIActionInputYesAction 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyFlowRunInputYesFlow 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyUIBatchInputYesSteps 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).

ParameterInTypeRequiredDescription
bodyFlowCheckInputYesFlow 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).

ParameterInTypeRequiredDescription
envqueryintegerNoOnly this device
limitqueryintegerNoMaximum 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).

ParameterInTypeRequiredDescription
ridpathstringYesRun 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).

ParameterInTypeRequiredDescription
ridpathstringYesRun 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).

ParameterInTypeRequiredDescription
cidpathstringYesConfirmation ID
waitqueryintegerNoMaximum 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).

ParameterInTypeRequiredDescription
cidpathstringYesConfirmation 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyHandoffReqNoHandoff 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyAppOpInputYesOperation 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
formatquerystringNolist

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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyAppInstallReqYesApp 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyFilePullReqYesPath 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyFilePushReqYesThe 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyFileSessionReqYesFile 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyEnvSyncReqNoSync 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).

ParameterInTypeRequiredDescription
idpathintegerYesTask 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).

ParameterInTypeRequiredDescription
envqueryintegerYesEnvironment ID
kindquerystringNoOnly 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).

ParameterInTypeRequiredDescription
idpathintegerYesBackup ID
bodyPackageCreateReqYesPackaging 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).

ParameterInTypeRequiredDescription
idpathintegerYesBackup ID
bodyAppRestoreReqNoRestore 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyBackupCreateReqYesBackup 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyAppBackupCreateReqYesApp 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyRestoreSetReqYesThe 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).

ParameterInTypeRequiredDescription
pidpathstringYesPackage 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).

ParameterInTypeRequiredDescription
pidpathstringYesPackage 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).

ParameterInTypeRequiredDescription
pidpathstringYesPackage ID
bodyShareCreateReqNoValidity 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).

ParameterInTypeRequiredDescription
bodyPackageImportReqYesImport 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).

ParameterInTypeRequiredDescription
bodyPackageInspectReqYesUpload 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).

ParameterInTypeRequiredDescription
bodyPackageUploadReqYesFile 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: .

ParameterInTypeRequiredDescription
bodyBatchInputYesSelector 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID
bodyRunCommandInputYesCommand 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).

ParameterInTypeRequiredDescription
idpathintegerYesEnvironment ID

Returns HTTP 101, Upgraded to WebSocket.

Data types

These are the data types used in request bodies and responses, sorted by name.

AgentTask

FieldTypeRequiredDescription
IDintegerNoPrimary key
backupIdintegerNo
createdAtstringNoCreation time
detailstringNo
envIdintegerNo
errorCodestringNo
expiresAtstringNo
messagestringNo
parentIdintegerNo
percentintegerNo
providerIdintegerNo
sessionIdintegerNo
stagestringNo
statusstringNo
typestringNo
updatedAtstringNoUpdate time

AppBackupCreateReq

FieldTypeRequiredDescription
includeObbbooleanNoAlso back up the app's OBB data
packagestringYesApp package name
targetstringNoWhere to keep it: cloud (default) or local (only on the local node where the environment runs)

AppInstallReq

FieldTypeRequiredDescription
appIdsinteger[]YesApp IDs in the app library

AppItem

FieldTypeRequiredDescription
labelstringNoReadable name
packagestringNoPackage name
versionNamestringNoVersion name

AppListView

FieldTypeRequiredDescription
appsAppItem[]NoInstalled apps
devicestringNoThe device, written as env:<environment ID>
notestringNoA note when the list comes from the device instead
sourcestringNoWhere the list comes from: platform (the platform's list) or device (listed on the device)

AppOpInput

FieldTypeRequiredDescription
activitystringNoThe activity to launch
keepDatabooleanNoKeep the data when uninstalling
opstringYesOperation: launch, stop, clear, uninstall or update
packagestringYesApp package name

AppRestoreReq

FieldTypeRequiredDescription
ignoreVersionbooleanNoRestore even if the app version differs from the backup

AttestationView

FieldTypeRequiredDescription
checkAttestCheckViewNo
deliverystringNo
enrollmentStatusstringNo
keyboxFingerprintstringNo
keyboxRefintegerNo
keyboxStatusstringNo
leaseStatusstringNo
lockedbooleanNo
modestringNo
runtimeModestringNo
sourcestringNo
strongIntegritybooleanNo
supplystringNo
truststringNo

AttestCheckView

FieldTypeRequiredDescription
checkedAtstringNo
failedstringNo
keyboxMatchbooleanNo
rootKindstringNo
statestringNo

AttestSource

FieldTypeRequiredDescription
keyboxIdintegerNoThe keybox ID, when kind is user
kindstringNopool (the platform, default) or user (your own keybox)

automation.Bounds

FieldTypeRequiredDescription
bottomnumberNo
leftnumberNo
rightnumberNo
topnumberNo

automation.Selector

FieldTypeRequiredDescription
classstringNoClass name
descstringNoDescription
idstringNoResource ID
indexintegerNoIndex among several elements matching the same condition, from 0
textstringNoText equals
textContainsstringNoText contains
textRegexstringNoRegex the text matches

BackupCreateReq

FieldTypeRequiredDescription
dataEnvIdintegerNoThe data environment to back up; defaults to the one in use
ignoreWindowbooleanNoOn a local Linux node, run right away instead of waiting for the backup window
kindstringNoBackup type: full (default) or incremental
namestringNoBackup name
parentBackupIdintegerNoThe backup an incremental backup is based on
targetstringNoWhere to keep it: cloud (default) or local (only on the local node where the environment runs)

BackupShare

FieldTypeRequiredDescription
IDintegerNoPrimary key
createdAtstringNoCreation time
createdByintegerNo
downloadCountintegerNo
expiresAtstringNo
lastDownloadAtstringNo
maxDownloadsintegerNo
packageIdintegerNo
requireLoginbooleanNo
revokedAtstringNo
updatedAtstringNoUpdate time

BatchInput

FieldTypeRequiredDescription
appOpAppOpInputNoThe app operation, when kind is app-op
commandRunCommandInputNoThe command, when kind is run-command
kindstringYesAction type: ui-action, app-op or run-command
selectorSelectorSpecNoThe selected devices
uiActionUIActionInputNoThe UI action, when kind is ui-action

BatchItemResult

FieldTypeRequiredDescription
envIdintegerNoEnvironment ID
errorstringNoWhy it failed
okbooleanNoWhether this device succeeded
resultanyNoThis device's result, with the same structure as the single-device endpoint

Candidate

FieldTypeRequiredDescription
linestringNoThe element's compact line
refstringNoElement ID
scorenumberNo
selectorsautomation.Selector[]NoSuggested selectors that are unique on the current screen

ConfirmationView

FieldTypeRequiredDescription
actionstringNoThe held action
categoriesstring[]NoRisk categories
clientNamestringNoThe requester's client
createdAtstringNoCreation time
decidedAtstringNoWhen it was decided
envIdintegerNoEnvironment ID
executedAtstringNoWhen it ran
expiresAtstringNoExpiry time
idstringNoConfirmation ID
intentstringNoThe intent stated by the caller
skillNamestringNoThe requester's Skill
statusstringNopending, approved, denied, expired, cancelled or executed
summarystringNoAction summary
thumbstringNoScreenshot taken before the action
tokenKindstringNoType of the requester's credential
tokenNamestringNoName of the requester's credential
urlstringNoConfirmation page URL

ConnectResp

FieldTypeRequiredDescription
expiresAtstringNoExpiry time
hintstringNoHow to use it
sessionIdstringNoBridge session ID

ControlView

FieldTypeRequiredDescription
byYoubooleanNoWhether the current user took over
enabledbooleanNoWhether human takeover is turned on
envIdintegerNoEnvironment ID
lastActionAtstringNoTime of the latest automation action
reasonstringNoHandoff reason
sincestringNoWhen it entered the current state
statestringNoControl state: free, automating, human or waiting-human
urlstringNoViewer URL

Deviation

FieldTypeRequiredDescription
candidatesCandidate[]No
commandstringNo
expectIdentityNo
foregroundstringNo
foundHitNo
pathstringNo
reasonstringNo
resumeintegerNo
screenstringNo
selectorflow.SelectorNo
stepintegerNo

Drafted

FieldTypeRequiredDescription
flowa yunyoo.flow/2 flowNoThe generated flow
skippedintegerNoNumber of steps left out of the draft
varsstring[]NoVariables to pass at run time, for input that could not be copied verbatim

EnvBackup

FieldTypeRequiredDescription
IDintegerNoPrimary key
actorUserIdintegerNo
androidVersionstringNo
appPackagestringNo
appVersionCodeintegerNo
boundPackagestringNo
chainDepthintegerNo
createdAtstringNoCreation time
dataEnvIdintegerNo
deviceProfilestringNo
envIdintegerNo
errorCodestringNo
expiresAtstringNo
formatintegerNo
hasRuntimeStatebooleanNo
hasSecureStatebooleanNo
identityMatchbooleanNo
importPackageIdintegerNo
kindstringNo
locationstringNo
namestringNo
nodeIdintegerNo
parentBackupIdintegerNo
plainSizeintegerNo
purposestringNo
remarkstringNo
retryCountintegerNo
rootVariantstringNo
scheduledAtstringNo
sourcestringNo
statusstringNo
updatedAtstringNoUpdate time
usedBytesintegerNo

EnvScopeSpec

FieldTypeRequiredDescription
envIdsinteger[]NoThe environments, when kind is env
groupIdsinteger[]NoThe groups, when kind is group
kindstringNoRange: all, group or env

EnvSummary

FieldTypeRequiredDescription
groupIdintegerNoGroup ID
idintegerNoEnvironment ID
statusstringNoStatus
titlestringNoName

EnvSyncReq

FieldTypeRequiredDescription
stopAndSyncbooleanNoWhen true, shuts down first and then syncs

FilePullReq

FieldTypeRequiredDescription
pathstringYesPath of the file on the device

FilePushReq

FieldTypeRequiredDescription
tokenstringYesThe token returned by the upload session

FileSessionReq

FieldTypeRequiredDescription
namestringYesFile name
sizeintegerYesFile size in bytes

flow.Selector

FieldTypeRequiredDescription
classstringNoClass name
descstringNoDescription
idstringNoResource ID
indexintegerNoIndex among several elements matching the same condition, from 0
pointPointNoFallback coordinates when the element cannot be found, as a fraction of the screen width and height
textstringNoText equals
textContainsstringNoText contains
textRegexstringNoRegex the text matches

FlowCheckInput

FieldTypeRequiredDescription
flowobjectNoThe flow to check; give either this or steps
stepsobject[]NoThe step list to check
varsobjectNoKnown variable values

FlowCheckView

FieldTypeRequiredDescription
secretsstring[]NoSecret placeholder names used; the caller supplies the values on its own computer
stepsintegerNoNumber of steps
varsstring[]NoVariables to pass at run time

FlowRunInput

FieldTypeRequiredDescription
atstringNoThe step position returned when the run paused
confirmationstringNoID of an approved confirmation; resume with the pause returned when the run paused
flowobjectNoContent of the yunyoo.flow/2 flow
fromintegerNoTop-level step to resume from, starting at 1
secretsobjectNoValues for secret placeholders, kept only in memory until the run ends
subintegerNoThe controlled action number returned when the run paused
varsobjectNoVariable values

FlowStarted

FieldTypeRequiredDescription
runIdstringNoRun ID
stepsintegerNoNumber of steps
taskIdintegerNoTask ID; track it with Get task

FlowView

FieldTypeRequiredDescription
codeintegerNoError code when it did not pass
confirmationConfirmationViewNoThe confirmation waiting for approval
deviationDeviationNoDeviation report: step position, expected element, a summary of the current screen and similar elements
failedStepResultNoThe first failed step
inspectstringNoCompact snapshot at the end
messagestringNoWhy it did not pass
pausePauseNoWhere it paused for a confirmation; pass it when resuming
resumeintegerNoStep to resume from, starting at 1; 0 means from the beginning
runIdstringNoRun ID
statusstringNopassed, failed, deviated, paused, cancelled or limited
stepsStepResult[]NoPer-step results

HandoffReq

FieldTypeRequiredDescription
reasonstringNoWhy you are handing off, shown to the user who takes over; when empty, only the current control state is returned

Hit

FieldTypeRequiredDescription
linestringNoThe element's compact line
refstringNoElement ID
selectorsautomation.Selector[]NoSuggested selectors that are unique on the current screen

Identity

FieldTypeRequiredDescription
classstringNo
descstringNo
idstringNo
textstringNo

ImportEnvSpec

FieldTypeRequiredDescription
attestationSourceAttestSourceNoAttestation source; defaults to the platform
bindAckbooleanNoConfirms that after switching to a bound app, third-party apps other than the bound app will be disabled
bindAppIdintegerNoThe bound app; defaults to the package's source
dataGibintegerNoDisk size (GiB)
deviceIdintegerNoSlot on the local node
deviceSourcestringNoDevice source: owned (a purchased device) or temporary (a temporary device)
egressConfirmstringNoEgress confirmation token returned by the check, used when the proxy and the package's anchor need confirming
groupIdintegerNoGroup
proxyIdintegerNoProxy
remarkstringNoRemark
skuIdintegerNoPlan ID
tagIdsinteger[]NoTags
titlestringNoName

ImportPlan

FieldTypeRequiredDescription
anchorobjectNoThe egress anchor in the package
attestationstringNoAttestation source
bindAckbooleanNoThe target environment has a bound app but the package's source did not; the real import must include bindAck
boundPackagestringNoThe bound app's package name carried over when creating an environment from the package; empty when the source was not bound
confirmTokenstringNoConfirmation token when the egress needs confirming; pass it as egressConfirm for the real import
deviceProfilestringNoThe device model the package is for
formatintegerNoPackage format version
hasSeedbooleanNoWhether the package contains a device identity seed
identitystringNoHow the identity will be handled
identityPublicobjectNoPublic values derived from the device identity in the package, redacted
kindstringNoPackage type
modestringNoImport mode
proxyGradestringNoHow well the proxy matches the anchor
rootVariantstringNoThe variant the package is for
runtimeStatebooleanNoWhether the runtime state will be restored
secureStatebooleanNoWhether the secure state will be restored
skuNamestringNoPlan name of the new environment
titlestringNoName of the new environment
verifybooleanNoThe real import must include your account password for re-verification

ImportTarget

FieldTypeRequiredDescription
envImportEnvSpecNoSettings for the new environment, when mode is env
envIdintegerNoTarget environment; leave it out when mode is env
modestringYesImport mode: restore, data-env, app, profile or env (create a new environment)

Node

FieldTypeRequiredDescription
boundsautomation.BoundsNoThe element's bounds on screen (pixels)
checkablebooleanNo
checkedbooleanNo
childrenNode[]NoChild elements
classNamestringNoClass name
clickablebooleanNo
contentDescstringNoDescription
editablebooleanNo
elementIdstringNoStable element ID
enabledbooleanNo
focusablebooleanNo
focusedbooleanNo
longClickablebooleanNo
packagestringNoPackage name of the app it belongs to
passwordbooleanNoWhether it is a password field; password fields return no text
refstringNoElement ID
resourceIdstringNoResource ID
scrollablebooleanNo
selectedbooleanNo
textstringNoText

NodeDoctor

FieldTypeRequiredDescription
failedstring[]NoChecks that did not pass
okbooleanNoWhether the health check passed

NodeSlots

FieldTypeRequiredDescription
totalintegerNoTotal slots
usedintegerNoSlots in use

NodeSummary

FieldTypeRequiredDescription
doctorNodeDoctorNoThe local node's health check result
execModestringNoHow the local node runs
lastSeenAtstringNoWhen it was last online
namestringNoName
nodeTypestringNoNode type
onlinebooleanNoWhether it is online
platformstringNoThe local node's operating system
providerIdintegerNoNode ID
scopestringNocloud (cloud node) or local (local node)
slotsNodeSlotsNoSlot usage

NormPoint

FieldTypeRequiredDescription
xnumberNoHorizontal coordinate as a fraction of the screen width, 0–1
ynumberNoVertical coordinate as a fraction of the screen height, 0–1

PackageCreateReq

FieldTypeRequiredDescription
escrowbooleanNoFor older passphrase packages, escrow the member keys so the passphrase can be recovered; paying users only
identityTransferbooleanNoAgree to transfer the device identity in the package to whoever imports it
includeSecureStatebooleanNoWhether to include the secure state; full packages include it by default
includeSeedbooleanNoWhether to include the device identity seed
kdfPackageKDFNoParameters used to derive wrapKeyB64
passwordstringNoAccount password, checked when the device identity is included
wrapKeyB64stringNoWrapping key for older passphrase packages (base64), derived from the passphrase on this computer; not needed when the platform has sealed export turned on

PackageCreateResult

FieldTypeRequiredDescription
fileNamestringNoPackage file name
packageIdstringNoPackage ID
taskIdintegerNoPackaging task ID

PackageDetail

FieldTypeRequiredDescription
IDintegerNoPrimary key
actorUserIdintegerNo
androidVersionstringNo
appPackagestringNo
backupIdintegerNo
createdAtstringNoCreation time
deviceProfilestringNo
downloadCountintegerNo
envIdintegerNo
envSegmentbooleanNo
errorCodestringNo
errorMsgstringNo
escrowbooleanNo
expiresAtstringNo
fileNamestringNo
formatintegerNo
hasRuntimeStatebooleanNo
hasSecureStatebooleanNo
hasSeedbooleanNo
identityTransferbooleanNo
kdfPackageKDFNo
keyIdstringNo
kindstringNo
originShareIdintegerNo
packageIdstringNo
rewrapCountintegerNo
rootVariantstringNo
sharesBackupShare[]No
sizeBytesintegerNo
sourcestringNo
statusstringNo
taskIdintegerNo
updatedAtstringNoUpdate time

PackageImportReq

FieldTypeRequiredDescription
bindAckbooleanNoConfirms 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
dataEnvNamestringNoName to use when importing as a data environment
dryRunbooleanNoWhen true, only returns the import plan and does not create a task
fileNamestringNoName of the uploaded file
identityModestringNoHow 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)
identityTransferbooleanNoMust be true when a machine credential takes over the identity in the package
ignoreVersionbooleanNoImport even if the versions differ
packageIdstringNoAn existing package ID; give either this or uploadSessionId
passwordstringNoAccount password, for re-verifying a sensitive action
restoreIdentitybooleanNoWhether to take over the device identity in the package; defaults to true
targetImportTargetYesImport target
uploadSessionIdstringNoUpload session ID
wrapKeyB64stringNoWrapping 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

FieldTypeRequiredDescription
packageIdstringNoPackage ID
planImportPlanNoThe import plan, when dryRun is set
taskIdintegerNoImport task ID; empty with dryRun

PackageInspectReq

FieldTypeRequiredDescription
fileNamestringNoPackage file name
uploadSessionIdstringYesUpload session ID

PackageKDF

FieldTypeRequiredDescription
iterationsintegerNoIteration count
saltB64stringNoSalt (base64)

PackageUploadReq

FieldTypeRequiredDescription
fileNamestringYesPackage file name, with the .wp extension
sizeintegerYesPackage size in bytes

packageUploadSession

FieldTypeRequiredDescription
headersobjectNoHeaders to send with the upload
modestringNoUpload method
partSizeintegerNoPart size (bytes)
partsUploadPartURL[]NoUpload URLs for each part
uploadSessionIdstringNoUpload session ID
urlstringNoURL for uploading the whole file at once

Pause

FieldTypeRequiredDescription
confirmationstringNoID of the confirmation waiting for approval
pathstringNoPosition of the paused step
stepintegerNoTop-level step number where it paused
subintegerNoWhich controlled action within this step, from 0

Point

FieldTypeRequiredDescription
xnumberNo
ynumberNo

provider.Bounds

FieldTypeRequiredDescription
bottomnumberNo
leftnumberNo
rightnumberNo
topnumberNo

RefCandidate

FieldTypeRequiredDescription
boundsprovider.BoundsNo
classNamestringNo
contentDescstringNo
refstringNo
resourceIdstringNo
textstringNo

RestoreSetReq

FieldTypeRequiredDescription
backupIdintegerNoThe full backup to restore; when empty, the pending restore is cancelled
bindAckbooleanNoConfirms 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
passwordstringNoAccount password, for re-verifying a sensitive action

RunCommandInput

FieldTypeRequiredDescription
argvstring[]YesCommand and arguments
cwdstringNoWorking directory
envobjectNoExtra environment variables
modestringNosync (default, waits for the result) or async (returns a task right away)
shellbooleanNoWhen true, the command is interpreted by the shell
timeoutMsintegerNoTimeout in milliseconds

RunCommandResult

FieldTypeRequiredDescription
channelstringNoExecution channel
duration_msintegerNoDuration in milliseconds
exit_codeintegerNoExit code
invoke_idstringNoCall ID
output_bytesintegerNoOutput size in bytes
statusstringNosucceeded, failed or timed_out
stderrstringNoStandard error
stderr_truncatedbooleanNoWhether standard error was truncated
stdoutstringNoStandard output
stdout_truncatedbooleanNoWhether standard output was truncated

RunCommandView

FieldTypeRequiredDescription
channelstringNoExecution channel
durationMsintegerNoDuration in milliseconds
exitCodeintegerNoExit code
invokeIdstringNoCall ID
outputBytesintegerNoOutput size in bytes
outputUrlstringNoDownload URL for output that was too large to return
statusstringNosucceeded, failed, timed_out or accepted (async request accepted)
stderrstringNoStandard error
stderrTruncatedbooleanNoWhether standard error was truncated
stdoutstringNoStandard output
stdoutTruncatedbooleanNoWhether standard output was truncated
taskIdintegerNoThe task ID, when mode is async; track it with Get task

RunView

FieldTypeRequiredDescription
clientNamestringNoClient
endedAtstringNoEnd time
entrystringNoEntry point
envIdintegerNoEnvironment ID
failedStepsintegerNoNumber of failed steps
idstringNoRun ID
itemsStepView[]NoPer-step records
skillNamestringNoSkill
startedAtstringNoStart time
statusstringNoRun result
stepsintegerNoNumber of steps
tokenKindstringNoCredential type
tokenNamestringNoCredential name

ScreenshotView

FieldTypeRequiredDescription
annotatedbooleanNoWhether element IDs are marked
formatstringNojpeg or png
heightintegerNoImage height
image_base64stringNoImage content (base64)
notesstring[]NoProcessing notes
scalenumberNoThe image's scale relative to the original resolution
snapshotintegerNoSnapshot version used for the marks
source_heightintegerNoOriginal screen height
source_widthintegerNoOriginal screen width
widthintegerNoImage width

SelectorSpec

FieldTypeRequiredDescription
envIdsinteger[]NoSelects these environments
groupIdintegerNoSelects the devices in this group
tagIdintegerNoSelects the devices with this tag

ShareCreateReq

FieldTypeRequiredDescription
expiresInHoursintegerNoHours it stays valid
identityTransferbooleanNoAgree that the device identity in the package moves with the share; must be true for packages with a device identity
maxDownloadsintegerNoMaximum number of downloads
requireLoginbooleanNoNo longer used; claiming always requires signing in

ShareCreateResult

FieldTypeRequiredDescription
expiresAtstringNoExpiry time
shareIdintegerNoShare ID
shareUrlstringNoShare link; claiming requires signing in
tokenstringNoShare token, returned only this once

StatusView

FieldTypeRequiredDescription
capabilitiesstring[]NoCapabilities, such as textInput and refIdentity
controlstringNoControl state: free, automating, human or waiting-human
degradedbooleanNoWhether this is the degraded tier
interactablebooleanNoWhether the device can be interacted with now
protocolstringNoAutomation protocol version

StepResult

FieldTypeRequiredDescription
codeintegerNoError code
commandstringNoStep command
durationMsintegerNoDuration in milliseconds
effectstringNoEffect check
labelstringNoStep label
messagestringNoWhy it failed
okbooleanNoWhether it succeeded
pathstringNoStep position, such as steps[3]
skippedbooleanNoWhether it was skipped
stepintegerNoTop-level step number, starting at 1

StepView

FieldTypeRequiredDescription
atstringNoTime
codeintegerNoResult code
confirmationstringNoThe related confirmation
durationMsintegerNoDuration in milliseconds
effectstringNoEffect check
entrystringNoEntry point
identitystringNoThe target element's identity
intentstringNoThe intent stated by the caller
paramsstringNoParameter summary
seqintegerNoStep number
targetstringNoTarget element
thumbstringNoScreenshot taken after the action
toolstringNoTool
tracestringNoTrace ID

TaskView

FieldTypeRequiredDescription
IDintegerNoPrimary key
backupIdintegerNo
createdAtstringNoCreation time
detailstringNo
envIdintegerNo
errorCodestringNo
expiresAtstringNo
messagestringNo
parentIdintegerNo
percentintegerNo
providerIdintegerNo
resultobjectNoTask result; for flows, the run report
sessionIdintegerNo
stagestringNo
statusstringNo
typestringNo
updatedAtstringNoUpdate time

UIActionInput

FieldTypeRequiredDescription
actionstringNoAction 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
activitystringNoWhen until is package, the activity that must also be in front
clearbooleanNoWhen true, clears the input field first
codeintegerNoAndroid key code
durationMsintegerNoSwipe duration in milliseconds
editorActionintegerNoInput method action number
fromNormPointNoWhere the swipe starts, in normalized coordinates
idleMsintegerNoWhen until is idle, how many milliseconds the screen must stay unchanged
longPressMsintegerNoWhen greater than 0, long-presses for this many milliseconds
packagestringNoWhen until is package, the package name of the app to wait for in the foreground
pointNormPointNoNormalized coordinates, used instead of selector when no element is available
selectorobjectNoElement 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}}
submitbooleanNoWhen true, presses Enter after typing
textstringNoThe text to type
timeoutMsintegerNoWait limit in milliseconds
toNormPointNoWhere the swipe ends, in normalized coordinates
untilstringNoWait condition: gone, idle, animation or package; when empty, waits for the element given by selector to appear
verifybooleanNoWhen true, waits for the screen to settle and then checks whether the action took effect

UIActionResult

FieldTypeRequiredDescription
activitystringNoForeground activity after the action
candidatesRefCandidate[]NoCandidate elements when the target is not unique
effectstringNoEffect check: changed means the screen changed, unchanged means it did not, and unverified means it was not checked
error_codeintegerNoError code when it did not complete
matchedbooleanNoWhether the wait found its target
messagestringNoWhy it did not complete
okbooleanNoWhether the action completed
packagestringNoPackage name of the foreground app after the action
snapshotobjectNoThe UI structure some environments attach after the action
snapshot_versionintegerNoSnapshot version after the action
targetRefCandidateNoThe element actually acted on
timed_outbooleanNoWhether the wait timed out

UIBatchInput

FieldTypeRequiredDescription
atstringNoThe step position returned when the run paused
confirmationstringNoID of an approved confirmation; resume with the pause returned when the run paused
fromintegerNoTop-level step to resume from, starting at 1
inspectAtEndbooleanNoWhen true, attaches a compact snapshot taken at the end to the result
keepGoingbooleanNoWhen true, keeps going after a step fails
secretsobjectNoValues for secret placeholders, kept only in memory until the run ends
stepsobject[]NoStep list, with the same structure as steps in a yunyoo.flow/2 flow
subintegerNoThe controlled action number returned when the run paused
varsobjectNoVariable values

UIFindInput

FieldTypeRequiredDescription
allbooleanNoWhen true, also searches off-screen and invisible elements
classstringNoClass name; the last segment alone is enough
descstringNoDescription contains this text, case-insensitive
idstringNoResource ID; the package prefix can be left out
maxintegerNoMaximum number of matches to return
regexstringNoText or description matches this regex
textstringNoText contains this, case-insensitive

UIFindView

FieldTypeRequiredDescription
devicestringNoThe device, written as env:<environment ID>
hitsHit[]NoThe matched elements, up to max
snapshotintegerNoSnapshot version
textstringNoCompact lines of the matched elements, one per line
totalintegerNoTotal number of matches

UITreeView

FieldTypeRequiredDescription
activitystringNoForeground activity
capabilitiesstring[]NoCapabilities, such as textInput and refIdentity
degradedbooleanNoWhether this is the degraded tier
devicestringNoThe device, written as env:<environment ID>
formatstringNocompact or json
heightintegerNoScreen height (pixels)
packagestringNoPackage name of the foreground app
protocolstringNoAutomation protocol version
rootNodeNoThe UI tree, when format is json
snapshotintegerNoSnapshot version; include it when acting by element ID
textstringNoThe compact snapshot, when format is compact
widthintegerNoScreen width (pixels)

UploadPartURL

FieldTypeRequiredDescription
partNumberintegerNo
urlstringNo

UploadSessionResp

FieldTypeRequiredDescription
headersobjectNoHeaders to send with the upload
tokenstringNoThe token to use when pushing the file
urlstringNoUpload URL; PUT the file content to it

WhoAmIResp

FieldTypeRequiredDescription
appsstring[]NoPackage names of the apps the delegated token may operate
dialogsstring[]NoPackage names of system dialogs that stay allowed besides the listed apps
envScopeEnvScopeSpecNoThe devices the credential may operate
scopesstring[]NoThe credential's scopes
sealedPackagebooleanNoWhen true, newly exported packages are sealed by the platform and packaging needs no passphrase
tokenIdintegerNoCredential ID
toolsstring[]NoThe MCP tools this credential can use, in tool-list order
uidstringNoUser number
userIdintegerNoUser ID