ailoha.
Home/ Docs/ DevFlow Agent Protocol/ OpenAPI reference
Generated from OpenAPI

OpenAPI reference

Generated HTTP API reference for the Ailoha DevFlow Agent Protocol.

WebSocket reference Download OpenAPI YAML Download spec
API docs by Redocly

DevFlow Agent Protocol (1.0.0)

License: Ailoha Binary Distribution License

Framework-agnostic protocol for runtime app inspection, interaction, and debugging. Supports any UI framework (MAUI, React Native, Flutter, native Android/iOS, etc.).

agent

Agent discovery and status

Get agent status

Returns the agent's identity, platform, version, and running state.

Responses

Response samples

Content type
application/json
{
  • "agent": {
    },
  • "platform": "ios",
  • "device": {
    },
  • "app": {
    },
  • "running": true,
  • "capabilities": {
    },
  • "uptime": "string",
  • "extensions": {
    }
}

Get agent capabilities

Returns the capabilities and extensions supported by this agent.

Responses

Response samples

Content type
application/json
{
  • "agent": {
    },
  • "capabilities": {
    },
  • "extensions": {
    }
}

ui

UI tree inspection, element queries, screenshots

Get visual tree

Returns the full visual tree of the application. Windows are root nodes. Use query parameters to limit depth, select a tree layer, or scope to a subtree.

query Parameters
depth
integer >= 0

Maximum depth of the tree to return. Unlimited if omitted.

layer
string
Default: "framework"
Enum: "framework" "native" "render"

Which tree layer to return.

rootId
string

Element ID to scope the tree to a subtree.

include
Array of strings
Items Value: "properties"

Additional data to include with each element.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get element by ID

Returns a single element by its globally unique identifier.

path Parameters
id
required
string (ElementId)

Globally unique element identifier.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "parentId": "string",
  • "type": "string",
  • "fullType": "string",
  • "framework": "maui",
  • "automationId": "string",
  • "text": "string",
  • "value": "string",
  • "role": "button",
  • "traits": [
    ],
  • "state": {
    },
  • "bounds": {
    },
  • "gestures": [
    ],
  • "style": {
    },
  • "nativeView": {
    },
  • "frameworkProperties": { },
  • "children": [
    ]
}

Query elements with locator strategies

Searches the visual tree for elements matching the given locator strategy and value.

query Parameters
strategy
required
string (LocatorStrategy)
Enum: "accessibility-id" "css-selector" "type" "text" "xpath"

Locator strategy to use.

value
required
string

Locator value.

limit
integer >= 1
Default: 10

Maximum number of results.

include
Array of strings
Items Enum: "properties" "bounds"

Additional data to include with each element.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find element at coordinates

Returns the elements at the given screen coordinates, ordered deepest first (innermost element first).

query Parameters
x
required
number

X coordinate.

y
required
number

Y coordinate.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Capture screenshot

Captures a screenshot of the entire screen or a specific element.

query Parameters
elementId
string

Element to screenshot. If omitted, captures the full screen.

maxWidth
integer >= 1

Maximum width in pixels. The image is scaled down if wider.

scale
string
Default: "auto"
Enum: "native" "auto"

Scale mode. native returns at device pixel density; auto returns a reasonable size for agent consumption.

format
string
Default: "png"
Enum: "png" "jpeg"

Image format.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:element-not-found",
  • "title": "Element not found",
  • "status": 404,
  • "errorCode": "element-not-found"
}

Get element property value

Returns the current value of a named property on an element.

path Parameters
id
required
string (ElementId)

Globally unique element identifier.

name
required
string

Property name.

Responses

Response samples

Content type
application/json
{
  • "value": null
}

Set element property value

Sets the value of a named property on an element and returns the new value.

path Parameters
id
required
string (ElementId)

Globally unique element identifier.

name
required
string

Property name.

Request Body schema: application/json
required
value
required
any

The value to set.

Responses

Request samples

Content type
application/json
{
  • "value": null
}

Response samples

Content type
application/json
{
  • "value": null
}

ui-actions

UI interaction (tap, fill, scroll, gestures, etc.)

Tap element or coordinates

Taps on an element (by ID) or at absolute coordinates.

Request Body schema: application/json
required
elementId
string or null

Target element identifier. Either elementId or coordinates must be provided.

x
number or null

X coordinate for the tap. Used when tapping by position rather than element.

y
number or null

Y coordinate for the tap. Used when tapping by position rather than element.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "elementId": "string",
  • "x": 0,
  • "y": 0,
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Fill text into element

Clears any existing text and fills the element with the given text.

Request Body schema: application/json
required
elementId
required
string

Target input element identifier.

text
required
string

Text content to fill into the element.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "elementId": "string",
  • "text": "string",
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Clear text from element

Clears any text content from the specified element.

Request Body schema: application/json
required
elementId
required
string

Target input element identifier.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "elementId": "string",
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Focus element

Gives keyboard focus to the specified element.

Request Body schema: application/json
required
elementId
required
string

Target element identifier to receive focus.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "elementId": "string",
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Scroll element

Scrolls an element by delta, to an item index, or to a named position.

Request Body schema: application/json
required
elementId
string or null

Target scrollable element identifier. If null, scrolls the primary scrollable view.

deltaX
number

Horizontal scroll delta in device-independent pixels.

deltaY
number

Vertical scroll delta in device-independent pixels.

animated
boolean
Default: true

Whether the scroll should be animated.

itemIndex
integer or null >= 0

Index of the item to scroll to in a list or collection view.

groupIndex
integer or null >= 0

Index of the group containing the target item.

scrollToPosition
string or null
Enum: "makeVisible" "start" "center" "end" null

Alignment of the target item within the viewport after scrolling.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "elementId": "string",
  • "deltaX": 0,
  • "deltaY": 0,
  • "animated": true,
  • "itemIndex": 0,
  • "groupIndex": 0,
  • "scrollToPosition": "makeVisible",
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Navigate to route

Navigates the application to the specified route or page.

Request Body schema: application/json
required
route
required
string

Route or URI to navigate to.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "route": "string",
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Resize window

Resizes a window or element to the given dimensions.

Request Body schema: application/json
required
elementId
string or null

Target window element identifier. If null, resizes the main application window.

width
required
integer >= 1

Target width in device-independent pixels.

height
required
integer >= 1

Target height in device-independent pixels.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "elementId": "string",
  • "width": 1,
  • "height": 1,
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Go back

Performs a back navigation gesture in the application.

Request Body schema: application/json
required
include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Press key

Sends a key press event to the focused element or the application.

Request Body schema: application/json
required
key
required
string

Key identifier to press (e.g. 'Enter', 'Escape', 'Tab', 'a', 'F1').

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Perform complex gesture

Executes a sequence of pointer actions (move, down, up, pause) to perform complex gestures like swipe, pinch, or drag.

Request Body schema: application/json
required
required
Array of objects (GestureAction)

Ordered sequence of gesture actions to perform.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "include": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Execute batch actions

Executes multiple actions in sequence. Optionally continues on error.

Request Body schema: application/json
required
required
Array of objects (BatchAction)

Ordered list of actions to perform.

include
Array of strings (IncludeOption)
Items Enum: "screenshot" "tree"

Optional data to include in the response.

continueOnError
boolean
Default: false

Whether to continue executing remaining actions if one fails.

Responses

Request samples

Content type
application/json
{
  • "actions": [
    ],
  • "include": [
    ],
  • "continueOnError": false
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

webview

WebView inspection and interaction

List WebView instances

Returns all active WebView contexts in the application.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Execute JavaScript in WebView

Evaluates a JavaScript expression inside a WebView context and returns the result.

Request Body schema: application/json
required
expression
required
string

JavaScript expression to evaluate.

contextId
string or null

Target WebView context identifier. If null, uses the default or only available context.

returnByValue
boolean
Default: true

Whether to return the result by value (serialized) rather than by reference.

Responses

Request samples

Content type
application/json
{
  • "expression": "string",
  • "contextId": "string",
  • "returnByValue": true
}

Response samples

Content type
application/json
{
  • "result": null,
  • "exceptionDetails": {
    }
}

Get DOM snapshot

Returns a simplified snapshot of the DOM tree in the WebView.

query Parameters
contextId
string

WebView context ID. Uses the default context if omitted.

Responses

Response samples

Content type
application/json
{ }

CSS query in DOM

Executes a CSS selector query against the WebView DOM and returns matching nodes.

Request Body schema: application/json
required
selector
required
string

CSS selector to query the DOM.

contextId
string or null

Target WebView context identifier.

Responses

Request samples

Content type
application/json
{
  • "selector": "string",
  • "contextId": "string"
}

Response samples

Content type
application/json
[
  • { }
]

Get page source

Returns the HTML source of the WebView page.

query Parameters
contextId
string

WebView context ID. Uses the default context if omitted.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:element-not-found",
  • "title": "Element not found",
  • "status": 404,
  • "errorCode": "element-not-found"
}

Navigate WebView

Navigates the WebView to the specified URL.

Request Body schema: application/json
required
url
required
string

URL to navigate the WebView to.

contextId
string or null

Target WebView context identifier.

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "contextId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Click element in WebView

Clicks a DOM element matching the given CSS selector inside the WebView.

Request Body schema: application/json
required
selector
required
string

CSS selector of the element to click.

contextId
string or null

Target WebView context identifier.

Responses

Request samples

Content type
application/json
{
  • "selector": "string",
  • "contextId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Fill field in WebView

Clears and fills a DOM input element matching the given CSS selector.

Request Body schema: application/json
required
selector
required
string

CSS selector of the input element to fill.

text
required
string

Text content to fill into the input element.

contextId
string or null

Target WebView context identifier.

Responses

Request samples

Content type
application/json
{
  • "selector": "string",
  • "text": "string",
  • "contextId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Insert text in WebView

Inserts text into the currently focused element in the WebView without clearing existing content.

Request Body schema: application/json
required
text
required
string

Text to type into the focused element.

contextId
string or null

Target WebView context identifier.

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "contextId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Capture WebView screenshot

Captures a screenshot of the WebView content.

query Parameters
contextId
string

WebView context ID. Uses the default context if omitted.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:element-not-found",
  • "title": "Element not found",
  • "status": 404,
  • "errorCode": "element-not-found"
}

profiler

Performance profiling

Get profiling capabilities

Returns which profiling features are supported on the current platform.

Responses

Response samples

Content type
application/json
{
  • "platform": "string",
  • "managedMemorySupported": true,
  • "nativeMemorySupported": true,
  • "gcSupported": true,
  • "cpuPercentSupported": true,
  • "fpsSupported": true,
  • "frameTimingsEstimated": true,
  • "nativeFrameTimingsSupported": true,
  • "jankEventsSupported": true,
  • "uiThreadStallSupported": true,
  • "threadCountSupported": true
}

Start profiler session

Starts a new profiling session with the given sample interval.

Request Body schema: application/json
required
sampleIntervalMs
integer >= 1

Sampling interval in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "sampleIntervalMs": 1
}

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "startedAtUtc": "2019-08-24T14:15:22Z",
  • "sampleIntervalMs": 1,
  • "isActive": true
}

Stop profiler session

Stops an active profiling session.

path Parameters
id
required
string

Profiler session ID.

Responses

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "startedAtUtc": "2019-08-24T14:15:22Z",
  • "sampleIntervalMs": 1,
  • "isActive": true
}

Get profiler samples

Returns profiling samples, markers, and spans collected since the given cursors. Use cursor values from the previous response to poll for new data.

path Parameters
id
required
string

Profiler session ID.

query Parameters
sampleCursor
integer >= 0

Cursor for samples. Start at 0.

markerCursor
integer >= 0

Cursor for markers. Start at 0.

spanCursor
integer >= 0

Cursor for spans. Start at 0.

limit
integer >= 1

Maximum number of items to return per category.

Responses

Response samples

Content type
application/json
{
  • "sessionId": "string",
  • "samples": [
    ],
  • "markers": [
    ],
  • "spans": [
    ],
  • "sampleCursor": 0,
  • "markerCursor": 0,
  • "spanCursor": 0,
  • "isActive": true
}

Publish profiler marker

Publishes a timestamped marker event into the active profiling session.

Request Body schema: application/json
required
tsUtc
required
string <date-time> (Timestamp)

UTC timestamp when this marker was recorded.

type
required
string

Marker type category (e.g. 'gc', 'layout', 'navigation', 'user').

name
required
string

Human-readable name of the marker event.

payloadJson
string or null

Optional JSON-encoded payload with additional marker data.

Responses

Request samples

Content type
application/json
{
  • "tsUtc": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "name": "string",
  • "payloadJson": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Publish profiler span

Publishes a completed span into the active profiling session.

Request Body schema: application/json
required
spanId
required
string

Unique identifier for this span.

parentSpanId
string or null

Identifier of the parent span, or null for root spans.

traceId
string or null

Trace identifier grouping related spans.

startTsUtc
required
string <date-time> (Timestamp)

UTC timestamp when this span started.

Timestamp (string) or null

UTC timestamp when this span ended, or null if still in progress.

durationMs
required
number >= 0

Duration of the span in milliseconds.

kind
required
string

Kind of span (e.g. 'layout', 'render', 'navigation', 'network', 'user').

name
required
string

Human-readable name describing the operation.

status
string or null

Span status (e.g. 'ok', 'error', 'cancelled').

threadId
string or null

Identifier of the thread this span executed on.

screen
string or null

Screen or page name where this span occurred.

elementPath
string or null

Path to the element in the visual tree associated with this span.

tagsJson
string or null

Optional JSON-encoded tags with additional span metadata.

error
string or null

Error message if the span ended with an error.

Responses

Request samples

Content type
application/json
{
  • "spanId": "string",
  • "parentSpanId": "string",
  • "traceId": "string",
  • "startTsUtc": "2019-08-24T14:15:22Z",
  • "endTsUtc": "2019-08-24T14:15:22Z",
  • "durationMs": 0,
  • "kind": "string",
  • "name": "string",
  • "status": "string",
  • "threadId": "string",
  • "screen": "string",
  • "elementPath": "string",
  • "tagsJson": "string",
  • "error": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get performance hotspots

Returns aggregated performance hotspots from the profiling session.

query Parameters
limit
integer >= 1

Maximum number of hotspots to return.

minDurationMs
number >= 0

Minimum average duration in milliseconds.

kind
string

Filter by hotspot kind.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

network

Network request monitoring

List captured network requests

Returns captured HTTP requests, optionally filtered by host, method, or status code.

query Parameters
limit
integer >= 1

Maximum number of requests to return.

host
string

Filter by host name.

method
string

Filter by HTTP method.

statusCode
integer [ 100 .. 599 ]

Filter by status code.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear captured requests

Clears all captured network requests from the buffer.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:internal-error",
  • "title": "Internal error",
  • "status": 500,
  • "errorCode": "internal-error"
}

Get network request detail

Returns full details for a captured network request, including headers and body content.

path Parameters
id
required
string

Network request ID.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "method": "string",
  • "url": "http://example.com",
  • "host": "string",
  • "path": "string",
  • "statusCode": 100,
  • "statusText": "string",
  • "durationMs": 0,
  • "error": "string",
  • "requestContentType": "string",
  • "responseContentType": "string",
  • "requestSize": 0,
  • "responseSize": 0,
  • "requestHeaders": {
    },
  • "responseHeaders": {
    },
  • "requestBody": "string",
  • "responseBody": "string",
  • "requestBodyEncoding": "string",
  • "responseBodyEncoding": "string",
  • "requestBodyTruncated": true,
  • "responseBodyTruncated": true
}

logs

Application logs

Query application logs

Returns application log entries, optionally filtered by source and level.

query Parameters
limit
integer >= 1

Maximum number of log entries.

skip
integer >= 0

Number of entries to skip (for pagination).

source
string
Enum: "native" "webview" "framework"

Filter by log source.

level
string
Enum: "trace" "debug" "info" "warning" "error" "critical"

Minimum log level.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

device

Device info, sensors, BLE, jobs, permissions, geolocation

Get device info

Returns hardware and OS information about the device.

Responses

Response samples

Content type
application/json
{
  • "model": "string",
  • "manufacturer": "string",
  • "osVersion": "string",
  • "platform": "string",
  • "idiom": "string",
  • "architecture": "string"
}

Get display info

Returns display dimensions, density, and orientation.

Responses

Response samples

Content type
application/json
{
  • "width": 0,
  • "height": 0,
  • "density": 0,
  • "orientation": "portrait",
  • "refreshRate": 0
}

Get battery info

Returns battery level, state, and power source.

Responses

Response samples

Content type
application/json
{
  • "level": 1,
  • "state": "unknown",
  • "powerSource": "unknown"
}

Get connectivity info

Returns network connectivity status and connection profiles.

Responses

Response samples

Content type
application/json
{
  • "networkAccess": "none",
  • "connectionProfiles": [
    ]
}

Get app info

Returns application name, version, build number, and package ID.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "version": "string",
  • "buildNumber": "string",
  • "packageId": "string",
  • "theme": "string"
}

List available sensors

Returns the list of sensors and their availability/active status.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start sensor

Starts collecting data from the named sensor. Readings are delivered via the WebSocket sensor channel.

path Parameters
name
required
string

Sensor name (e.g. accelerometer, gyroscope, compass).

query Parameters
speed
string

Sensor update speed. Framework-dependent (e.g. "fastest", "game", "ui", "default").

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "available": true,
  • "active": true
}

Stop sensor

Stops collecting data from the named sensor.

path Parameters
name
required
string

Sensor name.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "available": true,
  • "active": true
}

List permissions

Returns the status of all known permissions.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Check permission status

Returns the current status of a specific permission.

path Parameters
name
required
string

Permission name (e.g. camera, location, microphone).

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "status": "unknown"
}

Get current location

Returns the device's current geographic location.

query Parameters
accuracy
string

Desired accuracy level.

timeout
integer >= 0

Timeout in milliseconds for the location request.

Responses

Response samples

Content type
application/json
{
  • "latitude": -90,
  • "longitude": -180,
  • "altitude": 0,
  • "accuracy": 0,
  • "timestamp": "2019-08-24T14:15:22Z"
}

List platform background jobs

Returns platform background jobs known to the agent. Android reports WorkManager identifiers, tags, states, and run attempts. iOS and Mac Catalyst report pending BGTaskScheduler requests.

Responses

Response samples

Content type
application/json
{
  • "platform": "string",
  • "type": "string",
  • "supported": true,
  • "runSupported": true,
  • "jobs": [
    ],
  • "error": "string"
}

Trigger a platform background job

Attempts to trigger the named platform background job. iOS and Mac Catalyst submit a BGTaskRequest for the identifier; pass type when the task is known to be an app refresh task. Android may report success=false when worker types and request inputs cannot be reconstructed safely from the listed identifier or tags.

path Parameters
identifier
required
string

Platform job identifier returned by the list endpoint.

Request Body schema: application/json
optional
type
string
Enum: "processing" "refresh"

iOS or Mac Catalyst BGTask request type. If omitted, the agent resolves it from pending requests when possible and otherwise defaults to processing.

Responses

Request samples

Content type
application/json
{
  • "type": "processing"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "supported": true,
  • "identifier": "string",
  • "type": "processing",
  • "message": "string",
  • "error": "string"
}

Get BLE monitor status

Returns Bluetooth Low Energy monitor status, including whether scanning is active, the number of buffered events, active stream subscribers, and whether native scanning is supported.

Responses

Response samples

Content type
application/json
{
  • "isScanning": true,
  • "eventCount": 0,
  • "subscriberCount": 0,
  • "scanSupported": true,
  • "error": "string"
}

List BLE events

Returns recent BLE events recorded by the agent, optionally filtered by event type.

query Parameters
limit
integer >= 0
Default: 100

Maximum number of events to return.

type
string

Optional BLE event type filter.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ]
}

Clear BLE events

Clears all buffered BLE events.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Start BLE scan

Starts native BLE scanning when supported by the current platform. Discovered advertisements are buffered as BLE events and streamed to BLE WebSocket subscribers.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

Stop BLE scan

Stops an active BLE scan.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "error": {},
  • "screenshot": "string",
  • "tree": [
    ]
}

storage

Preferences, secure storage, and sandboxed app files

List file storage roots

Lists logical file storage roots advertised by the agent. Absolute on-device paths are not returned. The shared implementation advertises appData when an app data directory is available.

Responses

Response samples

Content type
application/json
{
  • "roots": [
    ]
}

List storage files

Lists files and directories under an advertised storage root. The optional path is always relative to the selected root; rooted paths, .. traversal segments, and symlink/reparse-point traversal are rejected. Absolute on-device paths are not returned. Omit root to use the default appData root.

query Parameters
root
string
Default: "appData"

Storage root id. Defaults to appData. Use /api/v1/storage/roots to discover supported roots.

path
string

Relative subdirectory path. Omit or pass an empty string for the selected root.

Responses

Response samples

Content type
application/json
{
  • "root": "string",
  • "path": "string",
  • "entries": [
    ]
}

Download a storage file

Downloads a file under an advertised storage root and returns base64-encoded content. The path parameter is a single URI-encoded relative path; path separators inside it must be percent-encoded. Omit root to use the default appData root.

path Parameters
path
required
string

URI-encoded relative file path under the selected storage root.

query Parameters
root
string
Default: "appData"

Storage root id. Defaults to appData. Use /api/v1/storage/roots to discover supported roots.

Responses

Response samples

Content type
application/json
{
  • "root": "string",
  • "path": "string",
  • "size": 0,
  • "lastModified": "2019-08-24T14:15:22Z",
  • "contentBase64": "string"
}

Upload a storage file

Creates or overwrites a file under an advertised storage root. Parent directories are created automatically after path sandbox validation. Omit root to use the default appData root.

path Parameters
path
required
string

URI-encoded relative file path under the selected storage root.

query Parameters
root
string
Default: "appData"

Storage root id. Defaults to appData. Use /api/v1/storage/roots to discover supported roots.

Request Body schema: application/json
required
contentBase64
required
string <base64>

File content encoded as base64.

Responses

Request samples

Content type
application/json
{
  • "contentBase64": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "root": "string",
  • "path": "string",
  • "size": 0,
  • "lastModified": "2019-08-24T14:15:22Z"
}

Delete a storage file

Deletes a file under an advertised storage root. Omit root to use the default appData root.

path Parameters
path
required
string

URI-encoded relative file path under the selected storage root.

query Parameters
root
string
Default: "appData"

Storage root id. Defaults to appData. Use /api/v1/storage/roots to discover supported roots.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "root": "string",
  • "path": "string",
  • "message": "string"
}

List preferences

Returns all preference entries, optionally scoped to a shared container.

query Parameters
sharedName
string

Shared preference container name.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear all preferences

Deletes all preferences, optionally scoped to a shared container.

query Parameters
sharedName
string

Shared preference container name.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:internal-error",
  • "title": "Internal error",
  • "status": 500,
  • "errorCode": "internal-error"
}

Get preference value

Returns the value of a specific preference key.

path Parameters
key
required
string

Preference key.

query Parameters
type
string (PreferenceValueType)
Enum: "string" "int" "bool" "double" "float" "long" "datetime"

Expected value type for deserialization.

sharedName
string

Shared preference container name.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "value": null,
  • "type": "string"
}

Set preference value

Creates or updates a preference entry.

path Parameters
key
required
string

Preference key.

Request Body schema: application/json
required
value
required
any

The value to set for the preference.

PreferenceValueType (string) or null

Data type of the value. If null, the type is auto-detected from the JSON value.

sharedName
string or null

Shared preference container name. If null, uses the default container.

Responses

Request samples

Content type
application/json
{
  • "value": null,
  • "type": "string",
  • "sharedName": "string"
}

Response samples

Content type
application/json
{
  • "key": "string",
  • "value": null,
  • "type": "string"
}

Delete preference

Deletes a specific preference by key.

path Parameters
key
required
string

Preference key.

query Parameters
sharedName
string

Shared preference container name.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:element-not-found",
  • "title": "Not found",
  • "status": 404
}

Clear all secure storage

Deletes all values from secure storage.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:internal-error",
  • "title": "Internal error",
  • "status": 500,
  • "errorCode": "internal-error"
}

Get secure storage value

Returns the value stored under the given key in secure storage.

path Parameters
key
required
string

Secure storage key.

Responses

Response samples

Content type
application/json
{
  • "value": "string"
}

Set secure storage value

Stores a value in secure storage under the given key.

path Parameters
key
required
string

Secure storage key.

Request Body schema: application/json
required
value
required
string

The string value to store securely.

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete secure storage value

Deletes a specific value from secure storage.

path Parameters
key
required
string

Secure storage key.

Responses

Response samples

Content type
application/json
{
  • "type": "urn:devflow:error:element-not-found",
  • "title": "Not found",
  • "status": 404
}

extensions

Third-party extension routes

Call extension endpoint (GET)

Proxy route for third-party extension GET endpoints. The namespace uses reverse-domain notation (e.g. com.example.analytics). Available extensions and their self-describing tools are discoverable via GET /api/v1/agent/capabilities. The path segment represents the extension-defined relative path; agents may accept nested sub-paths.

path Parameters
namespace
required
string^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-...

Extension namespace in reverse-domain notation.

path
required
string

Extension-defined sub-path.

Responses

Response samples

Content type
application/json
null

Call extension endpoint (POST)

Proxy route for third-party extension POST endpoints. Request and response schemas are extension-defined and advertised by the tool descriptor in the capabilities response.

path Parameters
namespace
required
string^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-...

Extension namespace in reverse-domain notation.

path
required
string

Extension-defined sub-path.

Request Body schema: application/json
optional
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

Call extension endpoint (PUT)

Proxy route for third-party extension PUT endpoints. Request and response schemas are extension-defined and advertised by the tool descriptor in the capabilities response.

path Parameters
namespace
required
string^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-...

Extension namespace in reverse-domain notation.

path
required
string

Extension-defined sub-path.

Request Body schema: application/json
optional
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

Call extension endpoint (DELETE)

Proxy route for third-party extension DELETE endpoints. Available extension tools and behavior annotations are discoverable from GET /api/v1/agent/capabilities.

path Parameters
namespace
required
string^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-...

Extension namespace in reverse-domain notation.

path
required
string

Extension-defined sub-path.

Responses

Response samples

Content type
application/json
null