REST API
Control iPhones, Android phones, simulators and emulators attached to a Mac running Silan.
Draft contract for the Silan engine’s REST API. The MCP server is generated from the same operations
(see x-silan-mcp on each operation), so REST and MCP never drift apart.
Conventions:
- Local base URL is
http://127.0.0.1:47800(port is configurable; the engine writes the real port to~/Library/Application Support/Silan/engine.json). Only the loopback interface is bound. - Every request needs
Authorization: Bearer silan_sk_...(a local key) unless it arrives over the relay, where an OAuth 2.1 access token is used instead. - Requests with an
Originheader are refused unless the origin is on the engine’s allow list (protects against DNS rebinding and drive-by browser pages). - Coordinates default to native screenshot pixels, origin top-left, current orientation.
- Errors use RFC 9457
application/problem+jsonwith a stablecode; a failed action never returns 200. - Any mutating device call accepts
Prefer: respond-asyncand then returns 202 with a job. - Devices under another holder’s lease return 409
DEVICE_LEASED; pass the lease token inSilan-Lease.
The document has 64 operations in 17 groups.
| Group | Operations | What it covers |
|---|---|---|
| System | 2 | Engine health and versions. |
| Devices | 6 | Attached devices, their details and apps. |
| Observation | 6 | Screens, element trees and live views. |
| Actions | 2 | Taps, typing, gestures, buttons and app control. |
| Waits | 2 | Engine-side waits and one-off checks. |
| Leases | 3 | Claims so parallel agents never share a device. |
| Jobs | 2 | Long-running operations. |
| Device extras | 6 | Clipboard, location, notifications and test pushes. |
| Credentials | 3 | Person-confirms login hand-off and the password-manager bridge. |
| Scenarios | 1 | Multi-device scenario validation. |
| Runs | 6 | Scenario and routine runs, reports and artifacts. |
| Recordings | 3 | Synced multi-device recordings. |
| Agent | 6 | The built-in agent. |
| Routines | 3 | Saved and scheduled routines. |
| Safety | 8 | Approvals, stop-everything, policy and audit. |
| Admin | 4 | Keys and usage. |
| Events | 1 | Server-sent event stream. |
All operations
Section titled “All operations”| Operation | Method and path | Summary |
|---|---|---|
health |
GET /v1/health |
Engine liveness and component status |
version |
GET /v1/version |
Engine, API and MCP protocol versions |
listDevices |
GET /v1/devices |
List devices this key may see |
getDevice |
GET /v1/devices/{deviceId} |
One device with capabilities and health |
updateDevice |
PATCH /v1/devices/{deviceId} |
Rename or relabel a device |
listApps |
GET /v1/devices/{deviceId}/apps |
Installed apps |
installApp |
POST /v1/devices/{deviceId}/apps |
Install an app build (.ipa, .app, or .apk) from a path on this Mac |
uninstallApp |
DELETE /v1/devices/{deviceId}/apps/{appId} |
Uninstall an app |
observe |
GET /v1/devices/{deviceId}/observe |
The agent’s look at the screen - screenshot reference plus a compact element list |
screenshot |
GET /v1/devices/{deviceId}/screenshot |
Current screen as an image |
getScreenshot |
GET /v1/screenshots/{screenshotId} |
Fetch a recent screenshot by id (kept in memory for 10 minutes unless part of a run) |
getElements |
GET /v1/devices/{deviceId}/elements |
Full element tree |
findElements |
POST /v1/devices/{deviceId}/elements/find |
Find elements matching a query |
streamMjpeg |
GET /v1/devices/{deviceId}/stream.mjpeg |
Simple live view for local tools (loopback only; the remote view uses WebRTC) |
act |
POST /v1/devices/{deviceId}/actions |
Perform one action (tap, type, swipe, press a button, launch an app…) |
actBatch |
POST /v1/devices/{deviceId}/actions/batch |
Run several actions in order; stops at the first failure |
waitFor |
POST /v1/devices/{deviceId}/waits |
Wait inside the engine until a condition holds on this device |
check |
POST /v1/devices/{deviceId}/checks |
Evaluate a condition once and report pass or fail with evidence |
createLease |
POST /v1/leases |
Claim devices so no other agent drives them |
renewLease |
POST /v1/leases/{leaseId} |
Extend a lease |
releaseLease |
DELETE /v1/leases/{leaseId} |
Release devices |
getJob |
GET /v1/jobs/{jobId} |
Job status and result |
cancelJob |
DELETE /v1/jobs/{jobId} |
Cancel a job |
getClipboard |
GET /v1/devices/{deviceId}/clipboard |
Read the device clipboard (text only) |
setClipboard |
PUT /v1/devices/{deviceId}/clipboard |
Put text on the device clipboard |
setLocation |
PUT /v1/devices/{deviceId}/location |
Simulate a location (simulators, emulators, developer-mode devices) |
clearLocation |
DELETE /v1/devices/{deviceId}/location |
Stop simulating a location |
listNotifications |
GET /v1/devices/{deviceId}/notifications |
Notifications the engine has observed on this device |
sendTestPush |
POST /v1/devices/{deviceId}/push |
Send a test push to an app build you own |
fillCredential |
POST /v1/devices/{deviceId}/credentials/fill |
Type a saved credential into the focused field without revealing it |
requestPersonLogin |
POST /v1/devices/{deviceId}/credentials/request-person |
Hand the login to the person (default password mode) |
listCredentialSites |
GET /v1/credentials/sites |
Sites enabled for the password-manager bridge (names only, never secrets) |
validateScenario |
POST /v1/scenarios/validate |
Parse and statically check a scenario (roles, sync points, deadlocks, capabilities) |
listRuns |
GET /v1/runs |
Run history |
startRun |
POST /v1/runs |
Start a scenario run on bound devices |
getRun |
GET /v1/runs/{runId} |
Run status, per-role progress, failures |
cancelRun |
DELETE /v1/runs/{runId} |
Cancel a running scenario |
getReport |
GET /v1/runs/{runId}/report |
Run report as HTML, JUnit XML, or JSON |
listArtifacts |
GET /v1/runs/{runId}/artifacts |
Screenshots, videos, logs and trees produced by a run |
startRecording |
POST /v1/recordings |
Record several devices on one clock |
getRecording |
GET /v1/recordings/{recordingId} |
Recording status and files |
stopRecording |
DELETE /v1/recordings/{recordingId} |
Stop and finalize a recording |
startAgentTask |
POST /v1/agent/tasks |
Give the built-in agent a task on one or more devices |
getAgentTask |
GET /v1/agent/tasks/{taskId} |
Task status, steps and cost so far |
cancelAgentTask |
DELETE /v1/agent/tasks/{taskId} |
Stop the task |
steerAgentTask |
POST /v1/agent/tasks/{taskId}/messages |
Add guidance to a running task |
takeOver |
POST /v1/agent/tasks/{taskId}/takeover |
Pause the agent at the next step boundary and give input to the person |
handBack |
POST /v1/agent/tasks/{taskId}/handback |
Return control to the agent with an optional note |
listRoutines |
GET /v1/routines |
Saved and scheduled routines |
saveRoutine |
POST /v1/routines |
Save a routine from a finished agent task or a scenario |
runRoutine |
POST /v1/routines/{routineId}/runs |
Run a routine now |
listApprovals |
GET /v1/approvals |
Pending and recent approval requests |
getApproval |
GET /v1/approvals/{approvalId} |
One approval request |
decideApproval |
POST /v1/approvals/{approvalId} |
Approve or deny (person or admin scope only; an actor can never approve its own request) |
stopEverything |
POST /v1/stop |
Stop every agent, run, job and pressed input on every device, and refuse new actions until resumed |
resume |
DELETE /v1/stop |
Clear the stop (person or admin scope only) |
getPolicy |
GET /v1/policy |
Current safety policy profiles |
updatePolicy |
PUT /v1/policy |
Replace policy profiles (admin scope) |
listAudit |
GET /v1/audit |
Audit log entries |
listKeys |
GET /v1/keys |
Local API keys (never the secret) |
createKey |
POST /v1/keys |
Create a key; the secret is shown once |
revokeKey |
DELETE /v1/keys/{keyId} |
Revoke a key at once |
getUsage |
GET /v1/usage |
Model spend, run counts and device time |
streamEvents |
GET /v1/events |
Server-sent events for devices, jobs, runs, approvals and agent steps |