---
title: "One core primitive (the Lusiesta core protocol, one to one)"
method: POST
path: "/devices/{name}/op"
tags: ["AI agents"]
---

# One core primitive (the Lusiesta core protocol, one to one)

`POST /devices/{name}/op`

## Request

- Base URL: `https://api.clousd.com/v1`
- URL: `https://api.clousd.com/v1/devices/{name}/op`
- Auth: HTTP bearer

op and args as in core/protocol.py; data has the protocol's result shape. shell {argv, timeout} → {rc, out_b64, err_b64} runs argv as the phone's shell user and, like push, needs ADB access enabled for the device with the caller's IP in allow_ips (403 otherwise; the key replaces the relay's login code); at most 4 shell/push at a time per device (409 busy); commands that would reboot the device are refused; every command is logged. dump → {xml_z}; launch_app {package, activity}, start_activity {component}, force_stop {package} → {rc}; foreground → {package}; screenshot → {png_b64}; acquire, screen → {w, h}; release, tap {x, y}, long_press {x, y, ms}, swipe {x1, y1, x2, y2, ms}, key {code, meta}, text {value} (any language), clear_field → {}; ip_check → {ok, rotated, has_link, ip, country, city, timezone, current_time, error}.

## Request body

- object
  - `op` 'shell' | 'dump' | 'launch_app' | 'start_activity' | 'force_stop' | 'foreground' | 'screenshot' | 'acquire' | 'release' | 'tap' | 'long_press' | 'swipe' | 'key' | 'text' | 'clear_field' | 'screen' | 'ip_check', required
  - `args` object

## Response `200`

OK

- object
  - `ok` boolean
  - `data` object

## Other responses

- `400`: Error
- `403`: Error
- `409`: Error
- `501`: Error

---

[API](https://skmtc.dev/clousd/apis/clousd-api.md) · [All operations](https://skmtc.dev/clousd/apis/clousd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clousd/apis/clousd-api/revisions/0291ffd26ae3?raw)