Test Creation (Open API)

This section explains how to create tests by running a Test Suite within a project.
Both single Test Suite execution and multiple Test Suite execution APIs are covered.

Single Test Suite Execution #

Run a Test Suite in the specified project by sending an execution request.

Endpoint #

[POST] /openapi/v3/projects/{pid}/test-suite-runs

Authorization #

This API requires Basic Authentication using a combination of username and access_key.

Key	Type	Required	Default	Description
auth	(username, access_key)	Yes	–	Encrypted login credentials. Required for every API call.
username	string	Yes	–	Ptero login ID.
access_key	string	Yes	–	Access Key (not your password). Issued in Ptero › Top-right icon › Edit Profile › Access Key.

Note
Encode the string username:access_key in Base64 and include it in the Authorization header.

Path Parameter #

You must include the project ID in the API path.

Key	Type	Required	Default	Description
pid	int	Yes	–	Project ID.

Request Body #

Content-Type: multipart/form-data

When running a test, include the Test Suite ID and app information in the request body.

- test_suite_id: int
- device: str | None 
- os: "ANDROID" | "iOS"
- source_type: "app_id" | "file" | None
- app_file: bytes | None
- app_download_url: str | None
- app_id: str | None

Key	Type	Required	Default	Description
test_suite_id	int	Yes	–	ID of the Test Suite to run.
device	string \| None	No	“random_device”	Target device. “random_device” selects one from available devices.
os	“ANDROID” \| “iOS”	Yes	–	Operating system of the device. Case sensitive.
source_type	“app_id” \| “file” \| None	No	–	How the app is provided (by ID or file).
app_file	bytes \| None	No	–	Application file. – Android: .apk, .apks, .xapk – iOS: .ipa
app_download_url	string \| None	No	–	Application download URL. Must start with http:// or https://.
app_id	string \| None	No	–	Application ID. – Android: package name – iOS: bundle ID

Constraints

Only one of the following fields can be provided:
- source_type
- app_file
- app_download_url
- app_id
If two or more of these fields are included, a value error occurs.

Request Example (cURL) #

Run with Project-Registered App #

using source_type and random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/test-suite-runs" \
  -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \
  -F "test_suite_id=112233" \
  -F "os=iOS" \
  -F "source_type=app_id"

Note

Authorization must be Base64 encoded (username:access_key).

If no device is specified, random_device is applied automatically.

OS must be uppercase; in iOS, only i is lowercase.

Test creation fails if no matching app exists in the project.

Run with App File Upload and Specific Device #

using app_file and target_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/test-suite-runs" \
  -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \
  -F "test_suite_id=112233" \
  -F "device=SAMSUNG GALAXY NOTE8 / ANDROID 9" \
  -F "os=ANDROID" \
  -F "app_file=@/upload/your/file/path.apk"

Note

Authorization must be Base64 encoded (username:access_key).

test_suite_id specifies the Test Suite to execute.

device is explicitly set to SAMSUNG GALAXY NOTE8 / ANDROID 9.

os must be uppercase.

app_file must use one of the following extensions: .apk, .apks, .xapk, .ipa.

Run with App ID and Random Device #

using app_id and random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/test-suite-runs" \
  -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \
  -F "test_suite_id=112233" \
  -F "device=random_device" \
  -F "os=ANDROID" \
  -F "app_id=com.android.chrome"

Note

Authorization must be Base64 encoded (username:access_key).

test_suite_id specifies the Test Suite to execute.

If device is not provided, it defaults to random_device.

os must be uppercase.

Output #

content-type: application/json

Success Response #

{
  "error_code": 0,
  "reason": "",
  "result": "success",
  "data": {
    "session_id": 123456,
    "test_suite_run_id": 789012,
    "test_run_count": 5
  }
}

session_id – Identifier of the API call. Use this to check execution status or progress.
test_suite_run_id – Identifier of the Test Suite execution result. Use this to retrieve results at the Test Suite level.
test_run_count – Number of individual test runs generated from the Test Suite.

Error Response #

error_code	reason	description
401	Could not verify your access level	User not registered or invalid credentials.
V001	Invalid value	Invalid request value (e.g., string passed for test_suite_id).
N001	Just one application is allowed	More than one app field provided.
V003	Invalid project ID	Project does not exist.
A002	Access denied for project	No access rights to the project.
V008	Invalid test suite ID	Test Suite does not exist.
M001	Invalid app file : System app file can not be tested	System app file submitted.
M002	app file info extraction error	Failed to extract app file metadata.
M003	invalid app file extension	Unsupported app file extension.
A006	Too many tests in account	Test creation limit exceeded (data.allowed_test_creation_count included).
V004	Invalid scenario ID	Scenario does not exist (data.invalid_scn_ids included).
S006	Scenario file is Invalid or corrupted while getting test data	Scenario file missing or corrupted (data.not_exist_scns_file provided).
M006	Device info does not exist	Device information missing or list not retrieved.
M007	Project settings app info is Empty	No app matches the provided source_type in the project.
M008	Invalid app id	app_id is empty or exceeds 100 characters.
A007	The service is currently under system maintenance	Service under maintenance.
E0001	Internal Server Error	Server-side error.

Example 1: Authentication Failed #

This error occurs when the user information is invalid or the provided Access Key is incorrect.

{
  "response": "Could not verify your access level for that URL.",
  "status": 401,
  "headers": {
    "WWW-Authenticate": "Basic realm=\"Access key Required\""
  }
}

Example 2: V001 Error (Invalid Value) #

This error occurs when a string is provided for the test_suite_id field, which requires an integer.

{
  "data": [],
  "detail": {
    "errors": [
      {
        "input": "abc",
        "loc": ["test_suite_id"],
        "msg": "Input should be a valid integer, unable to parse string as an integer",
        "type": "int_parsing",
        "url": "https://errors.pydantic.dev/2.7/v/int_parsing"
      }
    ]
  },
  "errorCode": "V001",
  "error_code": "V001",
  "reason": "Invalid value",
  "result": "fail"
}

Multiple Test Suite Execution #

Run multiple Test Suites in a project with a single request.

Provide a test_suite_ids array to run tests in the given order.
If test_suite_ids is omitted, all Test Suites in the project are executed in alphabetical order by name.

Warning: If `test_suite_ids` is omitted, every Test Suite in the project will be executed.

Endpoint #

[POST] /openapi/v3/projects/{pid}/multi-test-suite-runs

Authorization #

This API requires Basic Authentication using a combination of username and access_key.

Key	Type	Required	Default	Description
auth	(username, access_key)	Yes	–	Encrypted login credentials. Required for every API call.
username	string	Yes	–	Ptero login ID.
access_key	string	Yes	–	Access Key (not your password). Issued from Ptero › Top-right icon › Edit Profile › Access Key.

Note
Encode the string username:access_key in Base64 and include it in the Authorization header.

Path Parameter #

Key	Type	Required	Default	Description
pid	int	Yes	–	Project ID. Must be included in the API path.

Request Body #

Content-Type: multipart/form-data

When running tests, include the Test Suite and application information in the request body.

- test_suite_id: int
- device: str | None
- os: "ANDROID" | "iOS"
- source_type: "app_id" | "file" | None
- app_file: bytes | None
- app_download_url: str | None
- app_id: str | None

Key	Type	Required	Default	Description
test_suite_ids	list[int]	No	–	List of Test Suite IDs to execute, in the given array order. If omitted, all Test Suites in the project are executed in alphabetical order.
device	string \| None	No	“random_device”	Target device. If not specified, a random available device is used.
os	“ANDROID” \| “iOS”	Yes	–	Operating system of the device. Case sensitive.
source_type	“app_id” \| “file” \| None	No	–	How the app is provided (by ID or file).
app_file	bytes \| None	No	–	Application file. – Android: .apk, .apks, .xapk – iOS: .ipa only
app_download_url	string \| None	No	–	Application download URL. Must start with http:// or https://.
app_id	string \| None	No	–	Application ID. – Android: package name – iOS: bundle ID

Constraints

Only one of the following fields can be provided:
- app_id
- app_file
- app_download_url
- source_type
If two or more of these fields are included in a request, a value error occurs.

Request Example (cURL) #

Run All Test Suites #

without test_suite_ids, using source_type and random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/multi-test-suite-runs" \
  -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \
  -F "os=iOS" \
  -F "source_type=app_id"

Note

Authorization header must include Base64-encoded username:access_key.

os must be uppercase; in iOS, only i is lowercase.

If test_suite_ids is not provided, all Test Suites in the project are executed in alphabetical order by name.

If device is not provided, random_device is assigned automatically.

Test creation fails if no app in the project matches both os and source_type.

Run Specific Test Suites #

with test_suite_ids, using app_file, and target device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/multi-test-suite-runs" \
  -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \
  -F "test_suite_ids=[112233, 445566, 778899]" \
  -F "device=SAMSUNG GALAXY NOTE8 / ANDROID 9" \
  -F "os=ANDROID" \
  -F "app_file=@/upload/your/file/path.apk"

Note

Authorization header must include Base64-encoded username:access_key.

test_suite_ids runs the Test Suites in the specified array order.

If a device is provided, tests are executed on that device.

os must be uppercase.

When using app_file, tests run based on the uploaded application file. Supported extensions: .apk, .apks, .xapk, .ipa.

Run All Test Suites #

without test_suite_ids, using app_id and random_device

curl -X POST "https://api.apptest.ai/openapi/v3/projects/123/multi-test-suite-runs" \
  -H "Authorization: Basic $(echo -n 'johndoe:1q2w3e4r' | base64)" \
  -F "device=random_device" \
  -F "os=ANDROID" \
  -F "app_id=com.android.chrome"

Note

Authorization header must include Base64-encoded username:access_key.

If test_suite_ids is not provided, all Test Suites in the project are executed in alphabetical order by name.

device=random_device executes tests on a randomly available device.

os must be uppercase.

app_id runs tests using the registered application ID (e.g., com.android.chrome).

Output #

content-type: application/json

Success Response #

{
  "error_code": 0,
  "reason": "",
  "result": "success",
  "data": {
    "session_id": 123456,
    "test_suite_runs": [
      {
        "test_suite_run_id": 11111,
        "test_run_count": 5
      },
      {
        "test_suite_run_id": 22222,
        "test_run_count": 3
      }
    ],
    "total_test_run_count": 8
  }
}

session_id – Identifier of the API call. Use this to query execution status or results later.
test_suite_runs – List of individual Test Suite execution results, including test_suite_run_id and test_run_count.
total_test_run_count – Total number of test runs created from the entire request.

Note

session_id is an identifier of the multiple Test Suite execution results.
To learn more, see [API Docs › Test Result Lookup (Open API)].

Error Response #

error_code	reason	description
401	Could not verify your access level	User not registered or invalid credentials.
V001	Invalid value	Invalid request value (e.g., string passed for test_suite_ids).
V003	Invalid project ID	Project does not exist.
A002	Access denied for project	No access rights to the project.
C007	test suite does not exist in project	No Test Suite exists in the project.
M001	Invalid app file : System app file can not be tested	System app file submitted.
M002	app file info extraction error	Failed to extract metadata from the app file.
M003	invalid app file extension	Unsupported app file extension.
A006	Too many tests in account	Test creation limit exceeded (data.allowed_test_creation_count included).
V004	Invalid scenario ID	Scenario does not exist (data.invalid_scn_ids included).
S006	Scenario file is Invalid or corrupted while getting test data	Scenario file missing or corrupted (data.not_exist_scns_file provided).
M006	Device info does not exist	Device information missing or list not retrieved.
M007	Project settings app info is Empty	No app matches the provided source_type in the project.
M008	Invalid app id	app_id is empty or exceeds 100 characters.
A007	The service is currently under system maintenance	Service under maintenance.
E0001	Internal Server Error	Server-side error.

Refer to Single Test Suite Run > Error Response Example for the error response format.

Still need help? We’re here for you.

Updated on 09-19-2025

Overview

Getting Started

Ptero User Guide

Stego User Guide

Scenario File Management

Additional Usage Guide

API Docs

Test Creation (Open API)

Single Test Suite Execution #

Endpoint #

Authorization #

Path Parameter #

Request Body #

Request Example (cURL) #

Run with Project-Registered App #

Run with App File Upload and Specific Device #

Run with App ID and Random Device #

Output #

Success Response #

Error Response #

Example 1: Authentication Failed #

Example 2: V001 Error (Invalid Value) #

Multiple Test Suite Execution #

Endpoint #

Authorization #

Path Parameter #

Request Body #

Request Example (cURL) #

Run All Test Suites #

Run Specific Test Suites #

Run All Test Suites #

Output #

Success Response #

Error Response #

Single Test Suite Execution #

Endpoint #

Authorization #

Path Parameter #

Request Body #

Request Example (cURL) #

Run with Project-Registered App #

Run with App File Upload and Specific Device #

Run with App ID and Random Device #

Output #

Success Response #

Error Response #

Example 1: Authentication Failed #

Example 2: V001 Error (Invalid Value) #

Multiple Test Suite Execution #

Endpoint #

Authorization #

Path Parameter #

Request Body #

Request Example (cURL) #

Run All Test Suites #

Run Specific Test Suites #

Run All Test Suites #

Output #

Success Response #

Error Response #

We’re here to help — just let us know.