REST API de longarm

El servidor HTTP de longarm expone endpoints bajo /api/....

URL base

La app muestra la URL activa cuando el servidor HTTP está iniciado.

http://192.168.1.23:8080

Autenticación

Si Require token está activado, envía:

Authorization: Bearer <token>

Si el token falta o no es válido, longarm devuelve:

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

Comportamiento común

Los cuerpos de POST y PUT deben ser JSON.
El tamaño máximo del cuerpo es 64 KiB.
Las capturas usan image/png.
Las exportaciones por lotes usan application/zip.
CORS está habilitado.

Estado e información del dispositivo

`GET /api/status`

Devuelve el estado del servidor y las rutas de gestos disponibles.

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

`GET /api/screen/info`

Devuelve información de la pantalla del dispositivo.

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

`GET /api/window/current`

Devuelve el nombre de paquete de la ventana en primer plano. Cuando Android puede confirmar que la clase de estado de ventana es una actividad, activityName contiene su nombre de clase completo; en caso contrario es null. El servicio de accesibilidad debe estar habilitado.

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

Endpoints de gestos

`POST /api/gesture/tap`

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

duration por defecto es 50. x e y pueden omitirse, en cuyo caso longarm usa la posición de la burbuja flotante. Con la inspección de UI habilitada, target puede usarse en lugar de x e y.

`POST /api/gesture/long_press`

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

duration por defecto es 1000. target puede usarse en lugar de x/y.

Gestos Plus

Estas rutas requieren longarm Plus:

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

Ejemplo de swipe (duration por defecto 300; startX/startY recurren a la posición de la burbuja flotante; startTarget/endTarget pueden usarse en lugar de pares de coordenadas):

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

Ejemplo de pinch (angle por defecto 0, duration por defecto 400, target puede usarse en lugar de x/y):

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

Ejemplo de two-finger swipe (spread por defecto 200, duration por defecto 400):

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

Ejemplo de rotate (duration por defecto 600, target puede usarse en lugar de x/y):

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

Si se llama a una ruta exclusiva de Plus sin Plus:

{ "error": "Plus subscription required" }

Respuesta de éxito de gesto

{ "success": true }

Reglas de validación de gestos

las coordenadas deben estar dentro de la pantalla
duration debe ser un número entero entre 1 y 60000
el angle de pinch debe estar entre -360 y 360
el barrido de rotate no puede superar 720 grados
algunos valores multitáctiles se validan contra límites de seguridad según el tamaño de pantalla

Endpoint de captura de pantalla

`GET /api/screenshot`

Devuelve bytes PNG. Sin parámetros de consulta, la captura se devuelve sin modificar.

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

Parámetros de cuadrícula:

Nombre	Por defecto	Notas
`gridSize`	ninguno	Requerido cuando se usa cualquier opción de cuadrícula. Acepta `8-4096` px, `0.1-100cm`, o `0.05-40in`/`inch`.
`gridColor`	`80FF0000`	hex `RRGGBB` o `AARRGGBB`
`gridWidth`	`1`	de `0.5` a `32`
`coordinates`	`false`	`true`/`false` o `1`/`0`
`scale`	`false`	`true`/`false` o `1`/`0`; no se puede combinar con `coordinates`

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

Endpoints de superposición (overlay)

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

Ambos devuelven:

{ "success": true }

Endpoints de apps e intents

`POST /api/app/open`

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

El nombre de paquete debe ser un nombre de paquete Android válido.

`POST /api/intent/open`

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

Campos admitidos: action (obligatorio), data, mimeType, packageName, className (requiere packageName), categories (array de strings), y extras (objeto con valores string, boolean o numéricos — máximo 32 claves, valores string de hasta 4096 caracteres).

Endpoints de AppFunctions

Estos endpoints usan Android AppFunctions y no requieren el servicio de accesibilidad. Android debe admitir AppFunctions, la app de destino debe exponer una función visible, y Android debe autorizar a longarm a descubrirla y ejecutarla.

`POST /api/app-functions/query`

Todos los campos son opcionales. Usa packageNames para limitar el descubrimiento a apps concretas, o filtra por el esquema de AppFunction:

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

La respuesta contiene count, truncated y functions. Cada función incluye su paquete, id, estado habilitado, descripciones, metadatos de parámetros/respuesta y los tipos de componentes referenciados.

`POST /api/app-functions/call`

Primero consulta, luego pasa los argumentos que coincidan con los metadatos de parámetros devueltos:

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

Las llamadas exitosas devuelven success, packageName, functionId y el result decodificado. Los valores de bytes usan Base64 y los valores android.net.Uri usan strings.

Endpoints de inspección de UI

Estas rutas requieren autenticación por bearer token y 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

Si la inspección de UI está deshabilitada:

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

Parámetros de consulta de GET /api/ui/tree:

window: por defecto active
maxDepth: por defecto 30, rango 1-50
maxNodes: por defecto 1000, rango 1-2000
includeInvisible: true/1
compact: true/1

GET /api/ui/windows devuelve los metadatos de ventana de la captura de accesibilidad actual.

Los selectores usados por find, wait, action, set_text y scroll pueden usar campos como nodeId, revision, text, contentDescription, viewId, className, role, packageName, index, state, ancestor y descendant. Para gestos con coordenadas, target, startTarget y endTarget también pueden usarse con resolución basada en selector.

Rutas de tareas por lotes

La estructura y el historial de tareas por lotes están documentados en Tareas por lotes.

Rutas 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 (campo opcional keepScreenOn en el cuerpo o como parámetro de consulta)
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)