canonical: https://jentic.com/apis/amazonaws.com/aws-device-farm

# AWS Device Farm

Jentic publishes the only available OpenAPI specification for AWS Device Farm, keeping it validated and agent-ready. AWS Device Farm lets you test mobile and web applications across real phones, tablets, and desktop browsers in the AWS cloud. The API covers the full mobile testing lifecycle - projects, device pools, uploads, runs, jobs, suites, and tests - as well as the desktop browser TestGrid for Selenium-based web testing. Use it when an agent or pipeline needs to provision device pools, kick off test runs against real hardware, and pull results without the AWS console.

## For AI agents

Run mobile and web app tests on real devices and Selenium browsers in AWS, manage projects and device pools, and retrieve run, job, and artifact results.

## Scope

Does not handle device emulation, beta distribution, or app store deployment - use for real-device test orchestration and Selenium browser testing only.

## Capabilities

- Schedule mobile test runs against real phones and tablets with ScheduleRun and a curated DevicePool
- Provision Selenium-based browser sessions on demand via CreateTestGridUrl and CreateTestGridProject
- Upload application binaries and test packages with CreateUpload and track ingestion status
- Curate device coverage by listing available devices, building DevicePools, and applying NetworkProfiles
- Inspect run, job, suite, and test results to identify failing devices, artifacts, and test cases
- Apply VPCEConfigurations and InstanceProfiles to give tests private network access to backend services

## Use cases

### Continuous Mobile Test Runs in CI

Wire Device Farm into a CI pipeline so every build of a mobile app runs against a curated pool of real Android and iOS devices. CreateUpload pushes the new APK or IPA, ScheduleRun launches the test against a DevicePool, and GetRun and ListJobs poll for completion before the pipeline reports pass or fail.

Example prompt: Call CreateUpload to push the new APK, ScheduleRun against a DevicePool of the top 10 Android devices, then poll GetRun until status is COMPLETED.

### Selenium Browser Testing via TestGrid

Run cross-browser Selenium tests on demand by creating a TestGrid project and requesting a TestGrid URL. The framework points its WebDriver at the issued URL, executes the suite, and Device Farm records artifacts and session results that can be pulled back via GetTestGridSession and ListTestGridSessionArtifacts.

Example prompt: Call CreateTestGridProject, then CreateTestGridUrl with an expiresInSeconds of 3600, and supply the returned URL to the Selenium WebDriver.

### Curate Device Pools for Coverage

Maintain DevicePools that reflect the customer device mix - top-selling Android phones, the latest iPhone generation, and a long-tail OS coverage pool. CreateDevicePool, UpdateDevicePool, and ListDevices let teams keep test coverage current as new devices are added to the Device Farm fleet.

Example prompt: Call ListDevices filtered to OS_VERSION GREATER_THAN 14, then CreateDevicePool named ios-current with those device ARNs.

### Agent-Driven Mobile Test Orchestration

An AI agent connected via Jentic can react to a new build event, locate the right Device Farm project, schedule a test run, and report failures back to the team - all without bespoke AWS SDK plumbing. Jentic returns the matching Device Farm operation and schema so the agent can sequence Upload, ScheduleRun, and GetRun calls correctly.

Example prompt: Search Jentic for 'schedule a Device Farm run', load the ScheduleRun schema, and execute it with the projectArn, appArn, devicePoolArn, and test specification.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=DeviceFarm_20150623.CreateProject | Create a Device Farm project |
| POST | /#X-Amz-Target=DeviceFarm_20150623.CreateUpload | Initiate an application or test upload |
| POST | /#X-Amz-Target=DeviceFarm_20150623.ScheduleRun | Schedule a test run against a device pool |
| POST | /#X-Amz-Target=DeviceFarm_20150623.CreateDevicePool | Create a device pool |
| POST | /#X-Amz-Target=DeviceFarm_20150623.CreateTestGridProject | Create a Selenium TestGrid project |
| POST | /#X-Amz-Target=DeviceFarm_20150623.CreateTestGridUrl | Request a Selenium TestGrid session URL |
| POST | /#X-Amz-Target=DeviceFarm_20150623.StopRun | Stop a running test run |

## Key resources

- **Project** — Top-level container that owns runs, uploads, and device pools.
- **Device Pool** — Curated set of real devices used as a target for runs.
- **Upload** — Application binary, test package, or auxiliary file used in a run.
- **Run** — Execution of a test against a device pool, with jobs per device.
- **TestGrid Project** — Selenium-based desktop browser testing scope and URLs.
- **Network Profile** — Network conditions (bandwidth, loss, delay) applied to runs.

## Why Jentic

- **Setup:** Wiring AWS Device Farm by hand means implementing AWS Signature v4 request signing, resolving the regional devicefarm host, and setting the X-Amz-Target header to route each of its many JSON actions to the right operation. Through Jentic you install once, import AWS Device Farm from the API Directory, store the AWS credentials once, and your agent calls it.
- **Permission scoping:** This API routes every call through a single endpoint with the action named in the request, covering operations like CreateProject, ScheduleRun, and CreateTestGridUrl. Limit the agent to the operations it needs, such as CreateUpload and ScheduleRun, so StopRun is not included unless you add it.
- **Credential handling:** Your AWS credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'schedule a Device Farm run against a device pool' or 'request a Selenium TestGrid URL', and Jentic returns the matching AWS Device Farm operation with its input schema so the agent calls the right endpoint without browsing the AWS service reference.

## Related APIs

- **AWS CodePipeline** — Continuous delivery service that can trigger Device Farm runs on each build.
- **Amazon AppStream 2.0** — Streams desktop applications rather than orchestrating test runs.
- **Amazon SageMaker** — Useful for training ML models that analyse Device Farm test artifacts.

## FAQ

### Why is there no official OpenAPI spec for AWS Device Farm?

AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AWS Device Farm via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the AWS Device Farm API use?

Device Farm uses AWS Signature Version 4 (HMAC) signing with an AWS access key ID and secret access key. Through Jentic, those credentials live encrypted in your Jentic One instance and are injected into signed requests at execution time, so the agent never sees the raw secret access key.

### Can I run Selenium tests on real desktop browsers with this API?

Yes. Use CreateTestGridProject and CreateTestGridUrl to provision a Selenium-compatible WebDriver endpoint. Point the Selenium framework at the returned URL and Device Farm records the session for later retrieval via GetTestGridSession.

### What are the rate limits for the AWS Device Farm API?

Device Farm shares standard AWS service quotas, which are managed per account and region rather than published as fixed per-second limits in the spec. The number of concurrent runs and devices is also gated by Device Farm's per-account limits, and ThrottlingException responses should trigger backoff.

### How do I schedule a mobile test run through Jentic?

Search Jentic for 'schedule a Device Farm run', load the ScheduleRun operation schema, then execute it with projectArn, appArn, devicePoolArn, and the test specification. Run pip install jentic to use the async SDK pattern.

### Does this API include the test results, or just the run metadata?

Run, job, suite, and test status are returned by GetRun, GetJob, GetSuite, and GetTest. Detailed artifacts such as logs, screenshots, and video are listed via ListArtifacts, and each artifact's downloadable URL is included in the response so they can be pulled directly.

### Can I limit what my agent is allowed to do with the AWS Device Farm API?

Yes. Because Jentic One is self-hosted, your own rules decide which AWS Device Farm operations and credentials the agent may use, even though every call routes through a single endpoint with the action named in the request. You can allow just the operations the agent needs, such as CreateUpload and ScheduleRun, and leave out others like StopRun, CreateTestGridUrl, or CreateProject. The stored AWS credentials are injected only for the operations you permit, so the agent cannot invoke actions outside that scope.