> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 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" }`

<Tip>
  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](/api-reference/introduction#finding-application-and-environment-short-ids).
</Tip>

### 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`

<Warning>
  Slack notification overrides do not work for projects with SSH Tunnel Proxy
  enabled.
</Warning>

**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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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)

```json theme={null}
{
  "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](/api-reference/run-status) or [rerun](/api-reference/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](/api-reference/run-status) – Poll run status and get test results
* [Rerun Tests](/api-reference/rerun) – Rerun all or failed tests from a run
* [Create Test Cases](/api-reference/test-cases) – Create test cases via API
* [API Introduction](/api-reference/introduction) – Authentication and IDs
* [OpenAPI specification](/api-reference/api.json) – Full API schema