Skip to main content

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)

CLI Alternative

For most use cases, we recommend using the TestingBot CLI instead of the REST API directly. The CLI handles uploading your app, flows and running tests in a single command: 

# Install the CLI
npm install -g @testingbot/cli

# Authenticate
testingbot login

# Run Maestro tests (handles upload + run automatically)
testingbot maestro app.apk ./flows --device "Pixel 8" --deviceVersion "14"

The CLI provides:

  • Automatic app and flow uploads
  • Real-time progress and streaming output
  • Automatic report downloads
  • Simpler authentication

Use the REST API directly when you need programmatic access or custom integration workflows.

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, .app or .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,
  "app": {
    "app_url": "https://...",
    "icon_url": "https://...",
    "app_version": "1.0.0",
    "bundle_id": "com.example.app"
  }
}

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,
  "flows": [
    {
      "id": 123,
      "name": "login_flow"
    }
  ]
}

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.
shardSplit integer No Group flows into N chunks, each chunk running on a separate device.
When omitted, each flow runs in its own session on the same device.
metadata object No CI/CD metadata stored with the run (e.g. commitSha, pullRequestId, repoOwner, repoName, branch). Displayed in the TestingBot dashboard. 
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"
      },
      "flows": [
        {
          "id": 123,
          "name": "login_flow",
          "report": "<xml>...</xml>",
          "requested_at": "2025-11-28T09:15:00.000Z",
          "completed_at": "2025-11-28T09:16:00.000Z",
          "status": "DONE",
          "test_case_id": 456
        }
      ]
    }
  ]
}

Error Responses

Status Code Description
429 Insufficient minutes available. Please upgrade your account to continue running Maestro tests.

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://...",
      "flows": [
        {
          "id": 123,
          "name": "login_flow",
        }
      ],
      "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": {},
      "flows": [
        {
          "id": 123,
          "name": "login_flow",
          "report": "<xml>...</xml>",
          "requested_at": "2025-11-28T09:15:00.000Z",
          "completed_at": "2025-11-28T09:16:00.000Z",
          "status": "DONE",
          "test_case_id": 456
        }
      ]
    }
  ],
  "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"
  },
  "flows": [
    {
      "id": 123,
      "name": "login_flow",
      "report": "<xml>...</xml>",
      "requested_at": "2025-11-28T09:15:00.000Z",
      "completed_at": "2025-11-28T09:16:00.000Z",
      "status": "DONE",
      "test_case_id": 456
    }
  ],
  "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
}

Frequently asked questions

Do I have to use the REST API or can I just use the TestingBot CLI?

For most workflows the TestingBot CLI is simpler since it handles upload, run and result polling in one command. The REST API is the right choice when you want fine-grained control, are integrating from a non-Node environment, or need to fetch artifacts asynchronously.

How do I upload my app and Maestro flows via the API?

POST your binary to the /maestro/app endpoint and your flow ZIP to /maestro/:id/tests with HTTP basic auth (API key and secret). The response returns IDs you use when starting the run. See the Upload App and Upload Maestro Flows sections.

How do I start a Maestro test run via the API?

POST to the run endpoint with the app and flow IDs from the upload step, plus your device target and any options. See the Run Maestro Tests section for the request body and response shape.

How do I fetch JUnit-style reports for CI?

GET the run's JUnit endpoint to receive a JUnit XML file with per-flow pass and fail results. Most CI runners can consume this format directly. See the JUnit Report section.

How do I cancel a running Maestro test?

POST to the stop endpoint with the run ID. See the Stop Maestro Run section for details.

Was this page helpful?
Last updated
TestingBot Docs