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

# Trigger a discovery run

> Queue a free-roam discovery run: the QA agent gets only a goal, decides what to test itself, and reports every bug it finds. Supports web, iOS, and Android; mobile platforms explore the uploaded app. FAILED means bugs were found.



## OpenAPI

````yaml /openapi.json post /v1/projects/{projectId}/discovery-runs
openapi: 3.0.0
info:
  title: TestArmy API
  version: 1.0.0
  description: >-
    AI-powered browser automation API for QA testing. Automate web testing
    workflows using natural language prompts.
servers:
  - url: https://tester.army/api
    description: Production API server
security: []
paths:
  /v1/projects/{projectId}/discovery-runs:
    post:
      tags:
        - Projects
      summary: Trigger a discovery run
      description: >-
        Queue a free-roam discovery run: the QA agent gets only a goal, decides
        what to test itself, and reports every bug it finds. Supports web, iOS,
        and Android; mobile platforms explore the uploaded app. FAILED means
        bugs were found.
      parameters:
        - schema:
            type: string
            description: Project ID or shortId
          required: true
          description: Project ID or shortId
          name: projectId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DiscoveryRunRequest'
      responses:
        '202':
          description: Discovery run queued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiscoveryRunResponse'
        '400':
          description: Bad Request - Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
        '429':
          description: Too Many Requests - Usage limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
        '504':
          description: Gateway Timeout - Test execution exceeded time limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error code or type
                  message:
                    type: string
                    description: Human-readable error message
                required:
                  - error
                  - message
      security:
        - bearerAuth: []
components:
  schemas:
    DiscoveryRunRequest:
      type: object
      properties:
        goal:
          type: string
          minLength: 8
          maxLength: 2000
          description: >-
            The exploration goal for the free-roam QA agent, e.g. "Explore the
            checkout flow and find bugs". The agent decides what to test; there
            is no predefined step list.
        targetUrl:
          type: string
          format: uri
          description: >-
            Optional URL to explore instead of the project's production URL. Web
            only.
        platform:
          type: string
          enum:
            - web
            - ios
            - android
          description: >-
            Target platform; defaults to web. Mobile platforms explore the
            uploaded app.
        appId:
          type: string
          description: >-
            Uploaded mobile app ID to explore. Defaults to the project's latest
            app for the platform.
        deviceModel:
          type: string
          enum:
            - iphone
            - ipad
          description: >-
            Mobile device variant within the platform (e.g. ipad on iOS). Omit
            for the default phone-sized device.
      required:
        - goal
      additionalProperties: false
    DiscoveryRunResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - queued
        runId:
          type: string
          format: uuid
        projectId:
          type: string
          format: uuid
        platform:
          type: string
          enum:
            - web
            - ios
            - android
      required:
        - status
        - runId
        - projectId
        - platform
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key authentication using Bearer token format

````