Skip to main content

​
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:
FieldTypeRequiredDescription
triggerstringNo"API" or "GITHUB" (defaults to API)
testPlanShortIdstringNoTest plan to execute (prefixed, e.g. pln_abc123)
applicationsarrayNoApplication overrides (environment, device preset)
notificationsarrayNoSlack notification overrides

​
GitHub Trigger Fields

When using trigger: "GITHUB" (typically from a CI/CD integration), you can include additional context fields:
FieldTypeRequiredDescription
actorstringNoGitHub username that triggered the workflow
branchstringNoBranch name
commitHashstringNoFull commit SHA
commitMessagestringNoCommit message
repositorystringNoRepository 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:
FieldTypeRequiredDescription
applicationShortIdstringYesApplication short ID (e.g. app_gXeBl2)
environmentobjectNoOverride environment: by URL or by existing env short ID
devicePresetShortIdstringNoDevice 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:
FieldTypeRequiredDescription
typestringYesMust be "slack"
channelstringYesSlack channel ID (e.g. C0478ABCDEF). QA.tech bot must have access.
notifyOnstringNo"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

StatusDescription
400Validation error, malformed body, empty notifications, Slack not configured, or inaccessible Slack channels. Response body includes message.
401Missing or invalid API key.
402Usage limit exceeded. “Organization has reached usage limit. Upgrade your account to continue.”
403Invalid token or organization suspended.
404Resource not found (project, test plan, or referenced entity).
500Server error.
All error responses can include a body such as: { "message": "Error message" }.