Skip to main content

​
Start Run API

The Start Run API allows you to programmatically trigger test runs for your projects. This endpoint is particularly useful for integrating QA.tech testing into your CI/CD pipelines and custom automation workflows. The Start Run API provides a single endpoint to create new test runs:
  • Endpoint: POST /projects/{projectId}/runs
  • Authentication: Bearer token (JWT)
  • Content-Type: application/json

​
Authentication

The Start Run API uses Bearer token authentication. Include your project’s API token in the Authorization header: 
Authorization: Bearer YOUR_API_TOKEN
You can obtain your project’s API token through the QA.tech dashboard in the project settings under “API & Integrations”.

​
Request Parameters

​
Path Parameters

ParameterTypeRequiredDescription
projectIdstringYesThe unique identifier of your QA.tech project

​
Headers

HeaderValueRequiredDescription
Content-Typeapplication/jsonYesMedia type of the request body

​
Request Body

The request body is optional and can contain the following fields: 
{
  "integrationName": "CircleCI",
  "testPlanShortId": "abc123"
}

​
Optional Fields

  • integrationName (string): Human-readable name of what triggered this test (defaults to “API”)
  • testPlanShortId (string): The short ID of the test plan to execute
  • applications (object): Optional application environment overrides for testing specific environments. Each application can specify either a new environment (with url and name) or reference an existing environment (with short_id).

​
Example Requests

​
Basic Test Run

curl -X POST https://app.qa.tech/api/projects/YOUR_PROJECT_ID/runs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanShortId": "abc123"
  }'

​
Test Run with Preview Environment

curl -X POST https://app.qa.tech/api/projects/YOUR_PROJECT_ID/runs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "Vercel Preview",
    "testPlanShortId": "abc123",
    "applications": {
      "frontend-app": {
        "environment": {
          "url": "https://pr-123-frontend.vercel.app",
          "name": "PR-123-Frontend"
        }
      },
      "backend-api": {
        "environment": {
          "short_id": "existing-env-456"
        }
      }
    }
  }'

​
Response Format

​
Success Response (200)

{
  "success": true,
  "run": {
    "id": "run_abc123def456",
    "shortId": "abc123",
    "url": "https://app.qa.tech/projects/project-123/results/abc123",
    "testCount": 5,
    "testPlan": {
      "id": "plan_xyz789",
      "name": "API Integration Tests"
    }
  }
}

​
Error Responses

​
Bad Request (400)

Returned when the request body is malformed or missing required fields.

​
Unauthorized (401)

Returned when the bearer token is invalid or expired.

​
Payment Required (402)

Returned when the organization has reached its usage limit.

​
Forbidden (403)

Returned when the organization is suspended or access is denied.

​
Not Found (404)

Returned when the specified project ID doesn’t exist.

​
Internal Server Error (500)

Returned when there’s an internal server error.

​
Use Cases

​
CI/CD Integration

Integrate test runs into your deployment pipeline to automatically test changes before they reach production.

​
Preview Environment Testing

Test pull request changes in isolated environments before merging.

​
Scheduled Testing

Set up recurring test runs to ensure ongoing quality assurance.

​
Custom Workflows

Trigger tests based on custom business logic or external events.

​
Integration Examples

​
GitHub Actions

name: QA.tech Test Run
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger QA.tech Test
        run: |
          curl -X POST https://app.qa.tech/api/projects/${{ secrets.QA_PROJECT_ID }}/runs \
            -H "Authorization: Bearer ${{ secrets.QA_API_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "integrationName": "GitHub Actions",
              "testPlanShortId": "${{ secrets.QA_TEST_PLAN_ID }}",
              "applications": {
                "frontend": {
                  "environment": {
                    "url": "${{ steps.deploy.outputs.preview-url }}",
                    "name": "PR-${{ github.event.number }}"
                  }
                }
              }
            }'
For a complete guide to GitHub Actions integration including the official QA.tech action and additional examples, see GitHub Actions.

​
OpenAPI Specification

For detailed API schema and additional examples, refer to the OpenAPI specification.
⌘I