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

# API Introduction

> Learn how to interact with QA.tech programmatically using our REST API

The QA.tech REST API allows you to programmatically control test runs, create test cases, check results, and integrate QA.tech into your CI/CD pipelines and automation workflows.

## What Can You Do?

* **Start test runs** programmatically from CI/CD pipelines or scripts
* **Create and list test cases** via API for importing tests or generating them dynamically
* **Check run status** and retrieve test results
* **Rerun tests** (all or a subset) from a previous run
* **Chat with AI assistant** to create tests and review changes via API
* **List applications and environments** for dynamic test configuration
* **Create remote tunnels** to test local environments
* **Upload mobile app builds** for iOS and Android testing
* **Get outbound IPs** for firewall allowlisting

## Quick Start

Here's a complete example to start a 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"}'
```

See [Start Test Run](/api-reference/runs/start-test-run) for all request options, including application/environment overrides.

To create or reuse a preview environment and persist auth or protection-bypass headers, pass `customHeaders` on `applications[].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 '{
    "testPlanShortId": "pln_abc123",
    "applications": [
      {
        "applicationShortId": "app_abc123",
        "environment": {
          "url": "https://pr-123.example.com",
          "name": "PR-123",
          "customHeaders": [
            {
              "domains": ["*.example.com"],
              "headers": {
                "x-vercel-protection-bypass": "YOUR_SECRET"
              }
            }
          ]
        }
      }
    ]
  }'
```

Omit `customHeaders` to leave stored headers unchanged. Pass `[]` to clear them. The GitHub Action uses the same field inside `applications_config`. See [Environment custom headers](/core-concepts/applications-and-environments#custom-headers).

For HTTP basic auth, pass `basicAuth` on the same environment object, for example `"basicAuth": [{ "domains": ["*.example.com"], "username": "preview", "password": "YOUR_PASSWORD" }]`. It follows the same omit / `[]` / replace rules. See [Environment basic auth](/core-concepts/applications-and-environments#basic-auth).

When you [create a test case](/api-reference/test-cases/create-test-case), QA.tech runs it once to generate its steps. That first run uses the application's default environment. To author a test against a preview deployment or a [remote tunnel](/api-reference/remote-tunnels) instead, pass `environment` with the same shape as above:

```bash theme={null}
curl -X POST https://api.qa.tech/v1/test-cases \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Checkout with saved card",
    "goal": "Buy a product using a saved card",
    "applicationShortId": "app_abc123",
    "environment": { "url": "https://pr-123.example.com" }
  }'
```

`environment` applies to that first run only. The test case keeps no environment of its own, so later runs use whatever environment the run or test plan selects. The URL must start with `http://` or `https://`.

**What you need:**

1. **API Token** - Created in **Organization Settings → API Keys** (the key is shown only once, at creation)
2. **Test Plan Short ID** - Prefixed ID from your test plan (e.g. `pln_abc123`). Alternatively pass `testCaseIds` to run specific test cases instead of a plan
3. **Other short IDs** as needed - Application, Environment, Config, Device Preset, Scenario (see table below)

## Authentication

All API endpoints (except a few public ones such as [Get Outbound IPs](/api-reference/infrastructure/get-outbound-ips) and the status badge endpoints) require Bearer token authentication. Include your API token in the `Authorization` header:

```bash theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

**Where to find your API token:**

1. Navigate to **Organization Settings → API Keys**
2. Create a new API key
3. Copy the key when it is shown — it will not be displayed again

<Note>
  API keys can be **project-scoped** or **organization-scoped**. With a
  project-scoped key the project is inferred from the token, so you can omit
  `projectShortId`. With an organization-scoped key you must pass
  `projectShortId` (e.g. `proj_abc123`) in the request body or query string of
  project-scoped endpoints.
</Note>

## Understanding Different IDs

QA.tech uses **prefixed short IDs** for most API resources. The prefix indicates the resource type. Some fields (e.g., dependency test case IDs in Create Test Case and Rerun endpoints) still use UUIDs and are documented on their respective pages:

| ID Type | Format | Where to Find | Used In API | Example |
| - | - | - | - | - |
| **Project Short ID** | `proj_` + alphanumeric | Project URLs, Settings | `projectShortId` (required for org-scoped keys) | `proj_abc123` |
| **Test Plan Short ID** | `pln_` + alphanumeric | Test plan URLs, Settings | `testPlanShortId` in request body | `pln_abc123` |
| **Application Short ID** | `app_` + alphanumeric | Settings → Applications & Envs | `applicationShortId` in applications array | `app_gXeBl2` |
| **Environment Short ID** | `env_` + alphanumeric | Settings → Applications & Envs → Environments | `environment.shortId` in applications array | `env_aB3xY9` |
| **Config Short ID** | `cfg_` + alphanumeric | Settings → Configs | `configShortIds` in test-cases body | `cfg_xyz789` |
| **Device Preset Short ID** | `preset_` + alphanumeric | Settings → Device Presets | `devicePresetShortId` in applications array | `preset_abc123` |
| **Scenario Short ID** | `scenario_` + alphanumeric | Scenarios | `scenarioShortId` in test-cases body | `scenario_abc123` |
| **Chat Conversation ID** | `chat_` + alphanumeric | Chat API response | `chatConversationShortId` in chat endpoints | `chat_abc123` |
| **Application Build ID** | `build_` + alphanumeric | Build API response | `applicationBuildShortId` in environment | `build_abc123` |

### Finding Application and Environment Short IDs

Application and Environment Short IDs are shown in the UI with their `app_` and `env_` prefixes.

<Steps>
  <Step title="Go to Applications & Envs">
    Navigate to **Settings → Applications & Envs** in your project
  </Step>

  <Step title="Find Short ID">
    The Application Short ID (e.g. `app_gXeBl2`) appears in the applications
    table. Use the three-dot menu (⋮) to **Copy Short ID**
  </Step>

  <Step title="Find Environment Short ID">
    Under **Settings → Applications & Envs → \[Select Application]**, the
    Environment Short ID (e.g. `env_aB3xY9`) appears in the **Environments**
    section. Use the copy action to copy it
  </Step>
</Steps>

## Base URL

All API requests are made to:

```
https://api.qa.tech/v1
```

## Migration from Legacy API

If you used the legacy API format:

* **Old:** `https://app.qa.tech/api/projects/{projectUuid}/runs`
* **New:** `https://api.qa.tech/v1/run` (project is inferred from your API key)

The old format may still work temporarily but is **deprecated**. Key changes in the current API:

* No `projectUuid` in the path; the project is determined by your API token
* All IDs use **prefixed short IDs** (e.g. `pln_abc123`, `app_gXeBl2`) instead of UUIDs where applicable
* Base URL is `https://api.qa.tech/v1`

Migrate to the new base URL and request format when possible.

## Related documentation

* **[Start a Run](/api-reference/runs/start-test-run)** - Trigger test runs programmatically
* **[Get Run Status](/api-reference/runs/get-run)** - Wait for test completion in CI/CD pipelines
* **[Rerun Tests](/api-reference/runs/rerun-run)** - Rerun all or failed tests from a previous run
* **[Create Test Cases](/api-reference/test-cases/create-test-case)** - Create tests via API
* **[List Test Cases](/api-reference/test-cases/list-test-cases)** - Retrieve test cases from your project
* **[Chat API](/api-reference/chat)** - Interact with the AI assistant programmatically
* **[Applications API](/api-reference/applications)** - List applications and environments
* **[Remote Tunnels API](/api-reference/remote-tunnels)** - Create tunnels to test local environments
* **[Application Builds API](/api-reference/application-builds)** - Upload mobile app builds
* **[Get Outbound IPs](/api-reference/infrastructure/get-outbound-ips)** - Retrieve IPs for firewall allowlisting
* **[View OpenAPI Spec](/api-reference/api.json)** - Complete API reference with all endpoints


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.