Maestro Testing API | TestingBot

Maestro API Overview

TestingBot provides a REST API to upload apps, run Maestro flows, and retrieve information about your Maestro projects and runs.

In the documentation below, a Maestro project using a :project_id consists of a mobile application that was uploaded together with a zipped set of Maestro flow files.

A Maestro project can have multiple test runs, depending on how many device configurations (capabilities) you specified when you started the tests.

All API endpoints require authentication using your TestingBot API key and secret, which you can obtain from the Member area.

Base URL	Authentication
`https://api.testingbot.com/v1/app-automate/maestro`	HTTP Basic Auth (API key:secret)

Upload App

Upload your Android (.apk/.aab) or iOS (.ipa/.app) application to TestingBot. This creates a new Maestro project and returns a project ID.

Method	Endpoint
`POST`	`/app-automate/maestro/app`

Parameters

Name	Type	Required	Description
`file`	file	Yes	The app file to upload (.apk, .aab, .ipa, or .app.zip)

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/app" \
-F "file=@/path/to/your/app.apk"

Response

{
  "id": 17876
}

Save the returned id - you'll need it for uploading flows and running tests.

Upload Maestro Flows

Upload your Maestro flow files (as a .zip archive) to an existing project. This replaces any previously uploaded flows.

Method	Endpoint
`POST`	`/app-automate/maestro/:id/tests`

Parameters

Name	Type	Required	Description
`id`	integer	Yes	The project ID returned from the app upload
`file`	file	Yes	A .zip file containing your Maestro flow YAML files

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/tests" \
-F "file=@/path/to/flows.zip"

Response

{
  "id": 17876
}

Run Maestro Tests

Start running your Maestro flows on one or more devices. You can specify multiple device configurations to run tests in parallel.

Method	Endpoint
`POST`	`/app-automate/maestro/:id/run`

Parameters

Name	Type	Required	Description
`id`	integer	Yes	The project ID
`capabilities`	array	Yes	Array of device configurations to run tests on
`maestroOptions`	object	No	Additional Maestro options (version, env, flows, tags). See Test Options.

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:id/run" \
-d '{"capabilities":[{"platformName":"Android","version":"14","deviceName":"Pixel 8"}]}' \
-H "Content-Type: application/json"

Response

{
  "success": true,
  "id": 17876,
  "runs": [
    {
      "id": 18809,
      "capabilities": {
        "platformName": "Android",
        "version": "14",
        "deviceName": "Pixel 8"
      }
    }
  ]
}

Each entry in the runs array represents a test run on a specific device. Use the id of to check the run status.

List Maestro Projects

Retrieve a paginated list of all your Maestro projects.

Method	Endpoint
`GET`	`/app-automate/maestro`

Query Parameters

Name	Type	Default	Description
`offset`	integer	0	Number of records to paginate
`count`	integer	10	Number of records to return

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro"

Response

{
  "data": [
    {
      "id": 17876,
      "name": "Maestro Project 17876",
      "created_at": "2025-11-28T08:12:31.000Z",
      "updated_at": "2025-11-28T08:12:31.000Z",
      "completed": false,
      "app": {
        "app_url": "https://...",
        "icon_url": "https://...",
        "app_version": "2.7.50420",
        "bundle_id": "org.wikipedia"
      },
      "flows_url": "https://...",
      "runs": [18809, 18854, 18863, 18866]
    }
  ],
  "meta": {
    "offset": 0,
    "count": 10,
    "total": 25
  }
}

Get Maestro Project Info

Retrieve details about a specific Maestro project, including all its runs.

Method	Endpoint
`GET`	`/app-automate/maestro/:id`

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/:id"

Response

{
  "runs": [
    {
      "id": 18809,
      "status": "DONE",
      "capabilities": {
        "version": "16",
        "deviceName": "Pixel 9",
        "platformName": "Android"
      },
      "success": 1,
      "report": "",
      "options": {}
    }
  ],
  "success": true,
  "completed": true
}

Run Status Values

Status	Description
`WAITING`	Run is queued and waiting for a device
`READY`	The test is running on the device
`DONE`	Run has completed
`FAILED`	Run failed to complete

Get Run Info

Retrieve detailed information about a specific Maestro run. Use this to poll for completion status.

Method	Endpoint
`GET`	`/app-automate/maestro/:project_id/:run_id`

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id"

Replace :project_id with your project ID and :run_id with the run ID.

Response

{
  "id": 18809,
  "status": "DONE",
  "capabilities": {
    "version": "16",
    "deviceName": "Pixel 9",
    "platformName": "Android"
  },
  "success": 1,
  "report": "",
  "options": {},
  "completed": true
}

Poll this endpoint to check if the test has finished. The completed field will be true when the run has completed.

JUnit Report

Retrieve the JUnit XML report for a completed Maestro run. This is useful for CI/CD integration.

Method	Endpoint
`GET`	`/app-automate/maestro/:project_id/:run_id/junit_report`

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/junit_report"

Response

{
  "junit_report": "<?xml version=\"1.0\"?><testsuites>...</testsuites>"
}

The junit_report field contains the XML-formatted JUnit report generated by Maestro.

Stop Maestro Run

Stop a currently running Maestro test.

Method	Endpoint
`POST`	`/app-automate/maestro/:project_id/:run_id/stop`

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/maestro/:project_id/:run_id/stop"

Response

{
  "success": true
}