canonical: https://jentic.com/apis/openstf.io/openstf # Openstf Smartphone Test Farm Smartphone Test Farm (STF) is an open-source platform for remotely controlling and managing real Android smartphones from a browser. The REST API exposes operations for listing connected devices, fetching device details, managing user access tokens, reserving devices for a user, and opening or closing remote-control sessions. STF is widely deployed inside QA labs and mobile build farms where teams need shared access to a pool of physical handsets for manual testing, automation hooks, and reproducibility checks. The API is the same surface STF's web UI uses, so it covers the full lifecycle of a remote test session. ## For AI agents Reserve and control real Android devices in a Smartphone Test Farm pool - list devices, claim them for a user, and open or close remote-control sessions. ## Scope Does not handle iOS devices, app distribution, or test result reporting - use for Android device reservation and remote control only. ## Capabilities - List all devices attached to the STF cluster with their model, serial, and availability state - Fetch detailed metadata for a single device by serial including OS version and battery - Reserve a specific device for the authenticated user via POST `/user/devices` - Release a reserved device back to the pool with DELETE `/user/devices/{serial}` - Open a remote-control session on a device using POST `/user/devices/{serial}/remoteConnect` - Tear down a remote-control session with DELETE `/user/devices/{serial}/remoteConnect` - Inspect the authenticated user's profile and active access tokens ## Use cases ### On-Demand Device Reservation for CI A continuous integration pipeline running mobile UI tests can call POST `/user/devices` to claim a free device before kicking off Espresso or Appium tests, then DELETE `/user/devices/{serial}` when the run completes. The API enforces single-user ownership while held, so parallel CI jobs never collide on the same handset. STF returns the device serial that ADB can then connect to. Example prompt: Call GET /devices to find a device where present=true and using=false, then POST `/user/devices` with that serial to reserve it ### Manual QA Device Browser Build a custom QA portal listing every device in the STF cluster with current usage status. The /devices endpoint returns the full inventory with model, OS version, battery, and current user. Combine with `/user/devices/{serial}/remoteConnect` to open a screen-mirroring session for the QA engineer directly from the portal, avoiding the need to log into the STF UI separately. Example prompt: GET /devices and render a table of devices grouped by model with a 'connect' button that calls POST `/user/devices/{serial}/remoteConnect` ### Idle Device Reaper Operations teams running large device farms need to reclaim stale reservations. A scheduled job can list `/user/devices` to find handsets the current bot user holds, check the last-used timestamp, and release any past a threshold by calling DELETE `/user/devices/{serial}.` This keeps device utilization high without manual intervention. Example prompt: GET `/user/devices`, identify devices where the lastUsed timestamp is older than 1 hour, and call DELETE `/user/devices/{serial}` on each ### AI Agent Mobile Test Orchestrator An AI agent that authors and runs Android UI tests can use STF through Jentic to acquire a device, run the test suite, and release the handset, all without managing STF auth tokens directly. Jentic resolves the agent's intent ('reserve a device matching these criteria') to the right /devices and `/user/devices` calls and returns the serial the agent's test runner needs. Example prompt: Through Jentic, search 'reserve a smartphone for testing', filter for an Android 13 device, and return the assigned serial ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/devices` | List all devices in the STF cluster | | GET | `/devices/{serial}` | Get details for a specific device | | GET | `/user/devices` | List devices reserved by the current user | | POST | `/user/devices` | Reserve a device for the current user | | DELETE | `/user/devices/{serial}` | Release a reserved device | | POST | `/user/devices/{serial}/remoteConnect` | Open a remote-control session | | DELETE | `/user/devices/{serial}/remoteConnect` | Close a remote-control session | ## Key resources - **Devices** — List devices in the cluster and fetch per-device details by serial. - **User Devices** — Manage the current user's reserved devices - claim, release, list. - **Remote Connect** — Open and close remote-control sessions on a reserved device. - **User** — Inspect the authenticated user's profile and access tokens. ## Why Jentic - **Setup:** Wiring the Smartphone Test Farm API by hand means sending your access token in the authorization header and managing device reservation and remote-connect lifecycles across the fleet yourself. Through Jentic you install once, import the Smartphone Test Farm API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** STF puts the device serial in the URL path (`/user/devices/{serial}`), so a rule can pin your agent to one device: it can read and control that device and nothing else. You choose the operations it may call, so releasing a device or ending a remote connection is not included unless you add it. - **Credential handling:** Your STF access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'reserve an Android device' or 'open a remote control session', and Jentic returns the matching STF operation with its parameter schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **BrowserStack API** — Hosted real-device cloud covering Android and iOS, paid SaaS rather than self-hosted. - **Sauce Labs API** — Cloud test platform with real Android and iOS devices plus emulator support. - **Applitools API** — Visual AI test platform that pairs with a device source like STF for screenshot diffing. ## FAQ ### What authentication does the Smartphone Test Farm API use? STF uses an access token sent in the authorization header. Generate a token from the STF web UI under your user settings. Through Jentic, the token is stored encrypted and injected at request time so it never appears in agent logs or prompts. ### Can I reserve a specific device by model with the Smartphone Test Farm API? Not by model directly - POST `/user/devices` takes a serial. Call GET /devices first, filter the response by model, present, and using fields, then reserve the matching serial. STF holds reservations until you call DELETE `/user/devices/{serial}.` ### What are the rate limits for the Smartphone Test Farm API? STF is self-hosted in most deployments, so rate limits depend on the operator's nginx or API gateway configuration. The reference STF deployment does not enforce hard limits at the API layer; check with your cluster admin for any organisational caps. ### How do I open a remote-control session on a reserved device through Jentic? After reserving a device with POST `/user/devices`, search Jentic for 'open remote control session smartphone test farm', load the POST `/user/devices/{serial}/remoteConnect` schema, and execute with the serial. Jentic returns the WebSocket URL for the screen mirror session. ### Does the Smartphone Test Farm API support iOS devices? STF v2.x is Android-only - it relies on ADB for device control. For iOS device farms, look at services like BrowserStack or Sauce Labs which expose their own APIs for iOS pools. ### Can two users reserve the same device at the same time? No - STF enforces a single-owner reservation model. POST `/user/devices` on a device already reserved by another user will fail. The /devices response includes the using.email field so you can see who currently holds it before attempting to reserve. ### Can I limit what my agent is allowed to do with the Smartphone Test Farm API? Yes. Jentic One is self-hosted, so your own rules decide which STF operations and credentials the agent may use. Because the device serial sits in the URL path (`/user/devices/{serial}`), you can pin the agent to a single device so it can read and control only that handset, and you choose which calls it may make, granting GET /devices and POST `/user/devices/{serial}/remoteConnect` while withholding DELETE `/user/devices/{serial}` or DELETE `/user/devices/{serial}/remoteConnect` unless you add them. Your access token is held by your own instance and injected at execution time, never entering the agent's prompt or logs.