Start Run API

API endpoint for programmatically starting test runs

Start Run API

The Start Run API allows you to programmatically trigger test runs for your project. This endpoint is particularly useful for integrating QA.tech testing into your CI/CD pipelines and custom automation workflows.

• Endpoint: POST /run
• Authentication: Bearer token (project API token)
• Content-Type: application/json
• Base URL: https://api.qa.tech/v1

Authentication

Include your project’s API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

You can obtain your project’s API token in the QA.tech dashboard: Settings → Integrations → API. The project is inferred from the token, so you do not pass a project ID in the URL.

Request Body

The request body is optional. When omitted, the server defaults to trigger: "API" and runs using the project’s default test plan. All fields are optional:

Field	Type	Required	Description
trigger	string	No	"API" or "GITHUB" (defaults to API)
testPlanShortId	string	No	Test plan to execute (prefixed, e.g. pln_abc123)
applications	array	No	Application overrides (environment, device preset)
notifications	array	No	Slack notification overrides

GitHub Trigger Fields

When using trigger: "GITHUB" (typically from a CI/CD integration), you can include additional context fields:

Field	Type	Required	Description
actor	string	No	GitHub username that triggered the workflow
branch	string	No	Branch name
commitHash	string	No	Full commit SHA
commitMessage	string	No	Commit message
repository	string	No	Repository name (e.g. owner/repo)

These fields provide attribution and context in the QA.tech dashboard. They are ignored when trigger is "API" or omitted.

Application Overrides (applications)

applications is an array of objects. Each object has:

Field	Type	Required	Description
applicationShortId	string	Yes	Application short ID (e.g. app_gXeBl2)
environment	object	No	Override environment: by URL or by existing env short ID
devicePresetShortId	string	No	Device preset short ID (e.g. preset_abc123)

Environment override – use one of:

• New/preview environment: { "url": "https://...", "name": "Optional name" }
• Existing environment: { "shortId": "env_aB3xY9" }

Find Application and Environment Short IDs in Settings → Applications. Use the copy action for the Short ID (e.g. app_gXeBl2, env_aB3xY9). See API Introduction.

Slack Notification Overrides (notifications)

Use the notifications array to send per-run Slack updates:

Field	Type	Required	Description
type	string	Yes	Must be "slack"
channel	string	Yes	Slack channel ID (e.g. C0478ABCDEF). QA.tech bot must have access.
notifyOn	string	No	"always" (default) or "failure"

• always: Run started + final result summary
• failure: Only final summary when result is not PASSED

Slack notification overrides do not work for projects with SSH Tunnel Proxy enabled.

Validation & errors:

• Empty notifications array → 400 (array must contain at least one element)
• Slack not configured for project → 400 (“Slack integration is not configured for this project…”)
• Inaccessible channel(s) → 400 (“Slack channel override failed. Ensure the QA.tech bot has access to: …”)

Example Requests

Basic Test Run

curl -X POST https://api.qa.tech/v1/run \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"testPlanShortId": "pln_abc123"}'

Test Run with Preview Environment

Use url/name for a new preview environment, or shortId to reference an existing environment:

curl -X POST https://api.qa.tech/v1/run \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": "API",
    "testPlanShortId": "pln_abc123",
    "applications": [
      {
        "applicationShortId": "app_gXeBl2",
        "environment": {
          "url": "https://pr-123-frontend.vercel.app",
          "name": "PR-123-Frontend"
        }
      },
      {
        "applicationShortId": "app_abc123",
        "environment": { "shortId": "env_aB3xY9" }
      }
    ]
  }'

Test Run with Device Preset Override

curl -X POST https://api.qa.tech/v1/run \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanShortId": "pln_abc123",
    "applications": [
      {
        "applicationShortId": "app_gXeBl2",
        "devicePresetShortId": "preset_abc123"
      }
    ]
  }'

Test Run with Slack Notification Override

curl -X POST https://api.qa.tech/v1/run \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanShortId": "pln_abc123",
    "notifications": [
      { "type": "slack", "channel": "C0478ABCDEF", "notifyOn": "always" },
      { "type": "slack", "channel": "C0123FAIL42", "notifyOn": "failure" }
    ]
  }'

Response Format

Success (200)

{
  "success": true,
  "run": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "shortId": "abc123",
    "url": "https://app.qa.tech/p/your-project/results/abc123",
    "testCount": 5,
    "testPlan": {
      "name": "API Integration Tests",
      "shortId": "pln_xyz789"
    }
  }
}

Use run.shortId to get run status or rerun.

Error Responses

Status	Description
400	Validation error, malformed body, empty notifications, Slack not configured, or inaccessible Slack channels. Response body includes message.
401	Missing or invalid API key.
402	Usage limit exceeded. “Organization has reached usage limit. Upgrade your account to continue.”
403	Invalid token or organization suspended.
404	Resource not found (project, test plan, or referenced entity).
500	Server error.

All error responses can include a body such as: { "message": "Error message" }.

Related

• Get Run Status – Poll run status and get test results
• Rerun Tests – Rerun all or failed tests from a run
• Create Test Cases – Create test cases via API
• API Introduction – Authentication and IDs
• OpenAPI specification – Full API schema