Test Suite API Integration

Use this guide to trigger test suites from external systems using a Panto API key.

Base URL

All endpoints in this guide are relative to:

https://qa-app.getpanto.ai

Authentication

Pass your API key in the X-PANTO-API-KEY header.

X-PANTO-API-KEY: your_api_key_here

Endpoint

POST /api/v1/qa/external/testsuite/trigger

Request Body

{
  "app_id": "build_file_id",
  "tags": {
    "include": {
      "tag_name_1": ["value_1", "value_2"],
      "tag_name_2": ["value_3"]
    }
  },
  "devices": [
    {
      "device_name": "iPhone 13",
      "platform_version": "16.0"
    }
  ],
  "env_name": "staging",
  "context_name": "logged-in-user"
}

Request Fields

• app_id (string, required): Build file id to run against.
• tags (object, required): Test suite tag selector.
• tags.include (object, optional): Map of tag names to allowed values (dict[str, list[str]]).
• tags.exclude (object, optional): Map of tag names to blocked values (dict[str, list[str]]).
• tags.include_tags (object, optional): Alias for tags.include.
• tags.exclude_tags (object, optional): Alias for tags.exclude.
• devices (array, required): Device list to execute suites on.
• devices[].device_name (string, required): Device name.
• devices[].platform_version (string, required): Platform version.
• env_name (string, optional): Environment name.
• context_name (string, optional): Context name.

Exactly one tags selector is required.

• Send either tags.include (or tags.include_tags) or tags.exclude (or tags.exclude_tags).
• Sending both include and exclude in the same request is invalid.
• Sending neither include nor exclude is invalid.

Successful Response

{
  "message": "Triggered 3 test suite(s) matched.",
  "test_runs": [
    "testrun_01",
    "testrun_02",
    "testrun_03"
  ]
}

Validation and Error Cases

{
  "detail": "Environment not found"
}

{
  "detail": "No test suites found matching the provided tags"
}

{
  "detail": "Build file not found"
}

{
  "detail": "Context not found"
}

cURL Example

curl -X POST "https://qa-app.getpanto.ai/api/v1/qa/external/testsuite/trigger" \
  -H "Content-Type: application/json" \
  -H "X-PANTO-API-KEY: your_api_key_here" \
  -d '{
    "app_id": "build_file_id",
    "tags": {
      "include": {
        "tag_name_1": ["value_1", "value_2"],
        "tag_name_2": ["value_3"]
      }
    },
    "devices": [
      {
        "device_name": "iPhone 13",
        "platform_version": "16.0"
      }
    ],
    "env_name": "staging",
    "context_name": "logged-in-user"
  }'

Integration Notes

• This endpoint is for external API-key based triggering.
• Test runs are created asynchronously; use returned test_runs ids in your own tracking flow.
• Use stable tagging strategy on suites so CI jobs can target consistently.