longarm REST API

longarm 的 HTTP 服务器通过 /api/... 提供 REST 接口。

基础 URL

HTTP 服务器启动后，应用会显示当前可用的服务器地址。

http://192.168.1.23:8080

认证

如果启用了 Require token，请求需要包含：

Authorization: Bearer <token>

Token 缺失或无效时，longarm 会返回：

{ "error": "Missing or invalid bearer token" }

通用行为

POST 和 PUT 请求体必须是 JSON。
请求体最大为 64 KiB。
截图响应使用 image/png。
批处理导出响应使用 application/zip。
CORS 已启用。

状态和设备信息

`GET /api/status`

返回服务器状态和当前可用的手势路由。

{
  "status": "running",
  "version": "1.0.0",
  "plus": false,
  "uiInspection": false,
  "gestures": ["/api/gesture/tap", "/api/gesture/long_press"]
}

`GET /api/screen/info`

返回设备屏幕信息。

{ "width": 1080, "height": 2400, "density": 3.0 }

`GET /api/window/current`

返回当前前台窗口的包名。当 Android 能够确认窗口状态类为 activity 时， activityName 包含其完整类名；否则为 null。需要启用无障碍服务。

{
  "packageName": "com.android.settings",
  "activityName": "com.android.settings.Settings"
}

手势接口

`POST /api/gesture/tap`

{ "x": 540, "y": 1200, "duration": 50 }

duration 默认为 50。可以省略 x 和 y，此时 longarm 会使用悬浮球的位置。启用 UI 检查时，可以用 target 代替 x/y。

`POST /api/gesture/long_press`

{ "x": 540, "y": 1200, "duration": 1000 }

duration 默认为 1000。可以用 target 代替 x/y。

Plus 手势

以下接口需要 longarm Plus：

POST /api/gesture/swipe
POST /api/gesture/pinch
POST /api/gesture/two_finger_swipe
POST /api/gesture/rotate

swipe 示例（duration 默认 300；startX/startY 省略时回退到悬浮球位置；可以用 startTarget/endTarget 代替坐标对）：

{
  "startX": 540,
  "startY": 1800,
  "endX": 540,
  "endY": 600,
  "duration": 300
}

pinch 示例（angle 默认 0，duration 默认 400，可以用 target 代替 x/y）：

{
  "x": 540,
  "y": 1200,
  "startSpread": 400,
  "endSpread": 100,
  "angle": 0,
  "duration": 400
}

two-finger swipe 示例（spread 默认 200，duration 默认 400）：

{
  "startX": 540,
  "startY": 1800,
  "endX": 540,
  "endY": 600,
  "spread": 200,
  "duration": 400
}

rotate 示例（duration 默认 600，可以用 target 代替 x/y）：

{
  "x": 540,
  "y": 1200,
  "radius": 200,
  "startAngle": 0,
  "endAngle": 90,
  "duration": 600
}

如果在没有 Plus 的情况下调用仅限 Plus 的路由：

{ "error": "Plus subscription required" }

手势成功响应

{ "success": true }

手势校验规则

坐标必须在屏幕范围内
duration 必须是 1 到 60000 之间的整数
pinch 的 angle 必须在 -360 到 360 之间
rotate 的旋转角度不能超过 720 度
部分多点触控数值会依据屏幕尺寸做安全范围校验

截图接口

`GET /api/screenshot`

返回 PNG 数据。不带查询参数时，返回原始截图。

curl -H "Authorization: Bearer <token>" \
  http://<host>:<port>/api/screenshot > screenshot.png

网格查询参数：

名称	默认值	说明
`gridSize`	无	使用任何网格选项时必填。支持 `8-4096` px、`0.1-100cm` 或 `0.05-40in`/`inch`。
`gridColor`	`80FF0000`	`RRGGBB` 或 `AARRGGBB` 十六进制
`gridWidth`	`1`	`0.5` 到 `32`
`coordinates`	`false`	`true`/`false` 或 `1`/`0`
`scale`	`false`	`true`/`false` 或 `1`/`0`；不能与 `coordinates` 同时使用

curl -H "Authorization: Bearer <token>" \
  "http://<host>:<port>/api/screenshot?gridSize=1cm&gridColor=80FF0000&gridWidth=2&scale=true" \
  > screenshot-grid.png

悬浮层接口

POST /api/overlay/show
POST /api/overlay/hide

两者都返回：

{ "success": true }

应用与 Intent 接口

`POST /api/app/open`

{ "packageName": "com.android.settings" }

包名必须是有效的 Android 包名。

`POST /api/intent/open`

{
  "action": "android.intent.action.VIEW",
  "data": "https://example.com"
}

支持的字段：action（必填）、data、mimeType、packageName、 className（需要 packageName）、categories（字符串数组），以及 extras（包含字符串、布尔或数字值的对象 —— 最多 32 个键，字符串值最长 4096 个字符）。

AppFunctions 接口

这些接口使用 Android AppFunctions，不需要无障碍服务。要求 Android 支持 AppFunctions、目标应用暴露可见的函数，并且 Android 已授权 longarm 发现和执行该函数。

`POST /api/app-functions/query`

所有字段均为可选。使用 packageNames 限定发现范围，或按 AppFunction schema 过滤：

{
  "packageNames": ["com.example.notes"],
  "schemaCategory": "productivity",
  "schemaName": "createNote",
  "minSchemaVersion": 1,
  "maxResults": 100
}

响应包含 count、truncated 和 functions。每个函数包含其所属包、id、启用状态、描述、参数/返回值元数据，以及引用的组件类型。

`POST /api/app-functions/call`

先查询，再提供与返回的参数元数据匹配的参数：

{
  "packageName": "com.example.notes",
  "functionId": "createNote",
  "arguments": {
    "title": "Groceries",
    "body": "Milk and bread"
  }
}

调用成功时返回 success、packageName、functionId 以及解码后的 result。字节值使用 Base64，android.net.Uri 值使用字符串。

UI 检查接口

以下接口需要 bearer token 认证和 Allow UI inspection：

GET /api/ui/tree
GET /api/ui/windows
POST /api/ui/find
POST /api/ui/wait
POST /api/ui/action
POST /api/ui/set_text
POST /api/ui/scroll

如果 UI 检查被禁用：

{
  "success": false,
  "error": {
    "code": "UI_INSPECTION_DISABLED",
    "message": "UI inspection is disabled in longarm settings"
  }
}

GET /api/ui/tree 查询参数：

window：默认 active
maxDepth：默认 30，范围 1-50
maxNodes：默认 1000，范围 1-2000
includeInvisible：true/1
compact：true/1

GET /api/ui/windows 返回当前无障碍快照中的窗口元数据。

find、wait、action、set_text 和 scroll 使用的选择器可以包含 nodeId、revision、text、contentDescription、viewId、className、 role、packageName、index、state、ancestor 和 descendant 等字段。对于坐标手势，也可以使用 target、startTarget 和 endTarget 进行基于选择器的解析。

批处理路由

批处理任务的结构和历史记录见批处理任务。

REST 路由：

GET /api/batch
POST /api/batch
GET /api/batch/<id>
PUT /api/batch/<id>
DELETE /api/batch/<id>
POST /api/batch/run
POST /api/batch/<id>/run（可选的 keepScreenOn 请求体字段或查询参数）
GET /api/batch/status
GET /api/batch/history
GET /api/batch/history/<runId>
DELETE /api/batch/history/<runId>
DELETE /api/batch/history
GET /api/batch/history/<runId>/export（Plus）
GET /api/batch/history/<runId>/screenshots/<screenshotId>（Plus）

Longarm REST API

基础 URL

认证

通用行为

状态和设备信息

GET /api/status

GET /api/screen/info

GET /api/window/current