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 }

`GET /api/window/current`

Returns the package name of the current foreground window. When Android can confirm the window-state class is an activity, activityName contains its fully qualified class name; otherwise it is null. The accessibility service must be enabled.

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

Gesture endpoints

`POST /api/gesture/tap`

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

duration defaults to 50. x and y may be omitted, in which case longarm uses the floating overlay position. 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. target may be used instead of x/y.

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 (duration defaults to 300; startX/startY fall back to the floating overlay position; startTarget/endTarget may be used instead of coordinate pairs):

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

Example pinch (angle defaults to 0, duration defaults to 400, target may be used instead of x/y):

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

Example two-finger swipe (spread defaults to 200, duration defaults to 400):

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

Example rotate (duration defaults to 600, target may be used instead of x/y):

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

If a Plus-only route is called without Plus:

{ "error": "Plus subscription required" }

Gesture success response

{ "success": true }

Gesture validation rules

coordinates must be on-screen
duration must be a whole number from 1 to 60000
pinch angle must be between -360 and 360
rotate sweep cannot exceed 720 degrees
some multi-touch values are checked against screen-size safety bounds

Screenshot endpoint

`GET /api/screenshot`

Returns PNG bytes. Without query parameters, the screenshot is returned unchanged.

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

Grid query parameters:

Name	Default	Notes
`gridSize`	none	Required when any grid option is used. Accepts `8-4096` px, `0.1-100cm`, or `0.05-40in`/`inch`.
`gridColor`	`80FF0000`	`RRGGBB` or `AARRGGBB` hex
`gridWidth`	`1`	`0.5` to `32`
`coordinates`	`false`	`true`/`false` or `1`/`0`
`scale`	`false`	`true`/`false` or `1`/`0`; cannot be used with `coordinates`

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

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" }

The package name must be a valid Android package name.

`POST /api/intent/open`

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

Supported fields: action (required), data, mimeType, packageName, className (requires packageName), categories (string array), and extras (object with string, boolean, or numeric values — at most 32 keys, string values up to 4096 characters).

AppFunctions endpoints

These endpoints use Android AppFunctions and do not require the accessibility service. Android must support AppFunctions, the target app must expose a visible function, and Android must authorize longarm to discover and execute it.

`POST /api/app-functions/query`

All fields are optional. Use packageNames to limit discovery to specific apps, or filter by AppFunction schema:

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

The response contains count, truncated, and functions. Each function includes its package, id, enabled state, descriptions, parameter/response type metadata, and referenced component types.

`POST /api/app-functions/call`

Query first, then supply arguments matching the returned parameter metadata:

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

Successful calls return success, packageName, functionId, and the decoded result. Byte values use Base64 and android.net.Uri values use strings.

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

If UI inspection is disabled:

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

GET /api/ui/tree query parameters:

window: default active
maxDepth: default 30, range 1-50
maxNodes: default 1000, range 1-2000
includeInvisible: true/1
compact: true/1

GET /api/ui/windows returns window metadata from the current accessibility snapshot.

Selectors used by find, wait, action, set_text, and scroll can use fields such as nodeId, revision, text, contentDescription, viewId, className, role, packageName, index, state, ancestor, and descendant. For coordinate gestures, target, startTarget, and endTarget can also be used with selector-based resolution.

Batch routes

Batch task authoring and history are documented in Batch Tasks.

REST routes:

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 (optional keepScreenOn body field or query parameter)
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