Test Flow

Use this guide to trigger test flows from external systems (CI/CD, backend jobs, schedulers) using a Panto API key.

For shared connection details, see Overview.

Endpoint

POST /api/v1/qa/external/test-flow/trigger

Request Body

{
  "app_id": "build_file_id",
  "tags": {
    "include": {
      "tag_name_1": ["value_1", "value_2"],
      "tag_name_2": ["value_3"]
    }
  },
  "devices": [
    {
      "platform": "android",
      "device_name": "Pixel 6",  
      "platform_version": "14"
    }
  ],
  "env_name": "staging",
  "context_name": "logged-in-user"
}

Request Fields

• app_id (string, required): Build file id to run against.
• tags (object, required): Test flow 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.
• "_$NAME" (fixed tag key): Use inside tags.include_tags or tags.exclude_tags to match test flow names directly.
• devices (array, required): Device list to execute the flow on.
• devices[].platform (string, required): Platform identifier.
• 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.
• To match by test flow name directly, use the fixed tag key "_$NAME" inside tags.include_tags or tags.exclude_tags with one or more names.

Example:

{
  "tags": {
    "include_tags": {
      "_$NAME": ["Login smoke", "Checkout happy path"]
    }
  }
}

Successful Response

{
  "trigger_id": "trigger_01",
  "message": "Triggered 2 test flow(s) matched.",
  "test_runs": [
    "testrun_01",
    "testrun_02"
  ]
}

• trigger_id is the shared identifier for the created test runs. Use it to fetch aggregated run status later.

Validation and Error Cases

{
  "detail": "Environment not found"
}

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

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

{
  "detail": "Context not found"
}

cURL Example

curl -X POST "https://qa-app.getpanto.ai/api/v1/qa/external/test-flow/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": [
      {
        "platform": "android",
        "device_name": "Pixel 6",  
        "platform_version": "14"
      }
    ],
    "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.
• Keep tags consistent across your test flow catalog for predictable targeting.