longarm REST API

The longarm HTTP server exposes REST endpoints under /api/....

Base URL

The app shows the active server URL after the HTTP server starts.

http://192.168.1.23:8080

Authentication

If Require token is enabled, send:

Authorization: Bearer <token>

If the token is missing or invalid, longarm returns:

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

Common behavior

Request bodies must be JSON for POST and PUT routes.
Maximum request body size is 64 KiB.
Screenshot responses use image/png.
Batch export responses use application/zip.
CORS is enabled.

Status and device info

`GET /api/status`

Returns server state and currently available gesture routes.

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

`GET /api/screen/info`

Returns device screen information.

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

Gesture endpoints

`POST /api/gesture/tap`

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

duration defaults to 50. When UI inspection is enabled, target can be used instead of x and y.

`POST /api/gesture/long_press`

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

duration defaults to 1000.

Plus gestures

These routes require longarm Plus:

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

Example swipe:

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

Gesture validation checks screen bounds, duration ranges, and multi-touch safety limits.

Screenshot endpoint

`GET /api/screenshot`

Returns PNG bytes.

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

Optional grid query parameters include gridSize, gridColor, gridWidth, coordinates, and scale.

Overlay endpoints

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

Both return:

{ "success": true }

App and intent endpoints

`POST /api/app/open`

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

`POST /api/intent/open`

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

Supported fields include action, data, mimeType, packageName, className, categories, and extras.

UI inspection endpoints

These routes require bearer-token auth and 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

Selectors can use fields such as text, contentDescription, viewId, className, role, packageName, ancestor, and descendant.

Batch routes

Batch endpoints are available under /api/batch:

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
GET /api/batch/status
GET /api/batch/history
GET /api/batch/history/<runId>
GET /api/batch/history/<runId>/export (Plus)
GET /api/batch/history/<runId>/screenshots/<screenshotId> (Plus)

See Batch Tasks for task JSON and run behavior.

Longarm REST API