> ## 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 test run

> Execute a run for a given project. Supports API or GITHUB trigger. When using GITHUB trigger, provide actor, branch, commitHash, commitMessage, and repository. Use applications to override environment or device preset per run.



## OpenAPI

````yaml /api-reference/api.json post /v1/run
openapi: 3.0.0
info:
  title: QA.tech API
  version: 1.0.0
  contact:
    name: QA.tech
    url: https://qa.tech
    email: support@qa.tech
  description: API for triggering and managing AI-powered test runs
servers:
  - url: https://api.qa.tech
    description: Production
    variables: {}
security:
  - BearerAuth: []
tags:
  - name: Runs
  - name: Infrastructure
  - name: Test Cases
  - name: Application Builds
  - name: Status badge
  - name: Remote Tunnels
  - name: Chat
  - name: Applications
  - name: Features
  - name: Metrics
  - name: Release Checks
  - name: Projects
paths:
  /v1/run:
    post:
      tags:
        - Runs
      summary: Start test run
      description: >-
        Execute a run for a given project. Supports API or GITHUB trigger. When
        using GITHUB trigger, provide actor, branch, commitHash, commitMessage,
        and repository. Use applications to override environment or device
        preset per run.
      operationId: RunProject
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunRequest'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
components:
  schemas:
    RunRequest:
      type: object
      properties:
        trigger:
          type: string
          enum:
            - API
            - GITHUB
        actor:
          type: string
        branch:
          type: string
        commitHash:
          type: string
        commitMessage:
          type: string
        repository:
          type: string
        testPlanShortId:
          $ref: '#/components/schemas/TestPlanShortId'
        testCaseIds:
          type: array
          items:
            type: string
        applications:
          type: array
          items:
            $ref: '#/components/schemas/ApplicationOverride'
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/NotificationOverride'
        parameters:
          $ref: '#/components/schemas/RunParametersOverrides'
        projectShortId:
          allOf:
            - $ref: '#/components/schemas/ProjectShortId'
          description: >-
            Target a specific project by its prefixed short ID
            (proj-slug_shortId or proj_shortId), as returned by the projects
            API. Required for organization-scoped API keys; project-scoped keys
            may only pass their own project's short ID.
      description: >-
        Request body for triggering a test run. Supports GitHub trigger fields,
        application overrides, and optional `parameters` for config overrides
        (merged into the blueprint).
    RunResponse:
      type: object
      required:
        - success
        - run
      properties:
        success:
          type: boolean
        run:
          $ref: '#/components/schemas/Run'
    TestPlanShortId:
      type: string
      pattern: ^pln(-.+_.+|_.+)$
    ApplicationOverride:
      type: object
      required:
        - applicationShortId
      properties:
        applicationShortId:
          $ref: '#/components/schemas/ApplicationShortId'
        devicePresetShortId:
          $ref: '#/components/schemas/DevicePresetShortId'
        environment:
          $ref: '#/components/schemas/ApplicationEnvironmentOverride'
      description: Override application, environment, or device preset for a specific run
    NotificationOverride:
      type: object
      required:
        - type
        - channel
      properties:
        type:
          type: string
          enum:
            - slack
        channel:
          type: string
          description: >-
            Slack channel ID (e.g. `C0478ABCDEF`). The QA.tech Slack bot must
            have access to the channel.
        notifyOn:
          type: string
          enum:
            - failure
            - always
          description: >-
            `always` (default) sends run-started and final-result messages;
            `failure` sends only the final summary when the result is not
            PASSED.
      description: >-
        Per-run Slack notification override. Not supported for projects with SSH
        Tunnel Proxy enabled.
    RunParametersOverrides:
      type: object
      properties:
        configs:
          type: object
          additionalProperties: {}
          description: >-
            Config identifier → full config object (replaces stored config data
            when present).
        configsByEnvironment:
          type: object
          additionalProperties:
            type: object
            additionalProperties: {}
          description: Environment id → config identifier → full config object.
      description: >-
        Optional run-time parameter overrides merged into the blueprint (after
        test plan defaults). Use `configs` to replace full config payloads by
        config short id (map keys are strings such as `cfg_...` or
        human-readable slugs); use `configsByEnvironment` for
        environment-specific overrides (outer key is environment UUID).
    ProjectShortId:
      type: string
      pattern: ^proj(-.+_.+|_.+)$
    Run:
      type: object
      required:
        - id
        - shortId
        - url
        - testCount
        - testPlan
      properties:
        id:
          type: string
        shortId:
          type: string
        url:
          type: string
        testCount:
          type: integer
          format: int32
        testPlan:
          $ref: '#/components/schemas/TestPlan'
    ApplicationShortId:
      type: string
      pattern: ^app(-.+_.+|_.+)$
    DevicePresetShortId:
      type: string
      pattern: ^preset(-.+_.+|_.+)$
    ApplicationEnvironmentOverride:
      anyOf:
        - $ref: '#/components/schemas/ApplicationEnvironmentOverrideByUrl'
        - $ref: '#/components/schemas/ApplicationEnvironmentOverrideByShortId'
        - $ref: >-
            #/components/schemas/ApplicationEnvironmentOverrideByApplicationBuildShortId
    TestPlan:
      type: object
      required:
        - name
        - shortId
      properties:
        name:
          type: string
        shortId:
          $ref: '#/components/schemas/TestPlanShortId'
    ApplicationEnvironmentOverrideByUrl:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        name:
          type: string
    ApplicationEnvironmentOverrideByShortId:
      type: object
      required:
        - shortId
      properties:
        shortId:
          $ref: '#/components/schemas/EnvironmentShortId'
    ApplicationEnvironmentOverrideByApplicationBuildShortId:
      type: object
      required:
        - applicationBuildShortId
      properties:
        applicationBuildShortId:
          $ref: '#/components/schemas/ApplicationBuildShortId'
      description: >-
        Use a specific application build (from POST /v1/application/builds).
        Creates or reuses an environment with this build.
    EnvironmentShortId:
      type: string
      pattern: ^env(-.+_.+|_.+)$
    ApplicationBuildShortId:
      type: string
      pattern: ^build(-.+_.+|_.+)$
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer

````