Revyl Explorations API

openapi: 3.2.0
info:
  description: Revyl API
  title: Revyl Explorations API
  version: 1.0.0
servers:
- description: Production
  url: https://backend.revyl.ai
tags:
- name: Explorations
paths:
  /api/v1/explorations/apps/{app_id}:
    post:
      description: Launch an exploration run via the parent Hatchet workflow.
      operationId: launch_exploration_api_v1_explorations_apps__app_id__post
      parameters:
      - in: path
        name: app_id
        required: true
        schema:
          format: uuid
          title: App Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExplorationLaunchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorationLaunchResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Launch Exploration
      tags:
      - Explorations
  /api/v1/explorations/{run_id}:
    get:
      operationId: get_exploration_api_v1_explorations__run_id__get
      parameters:
      - in: path
        name: run_id
        required: true
        schema:
          format: uuid
          title: Run Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorationRunResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get Exploration
      tags:
      - Explorations
  /api/v1/explorations/{run_id}/cancel:
    post:
      description: Cancel a running exploration and all of its device lanes.
      operationId: cancel_exploration_api_v1_explorations__run_id__cancel_post
      parameters:
      - in: path
        name: run_id
        required: true
        schema:
          format: uuid
          title: Run Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorationCancelResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Cancel Exploration
      tags:
      - Explorations
  /api/v1/explorations/{run_id}/report:
    get:
      description: 'Run-report view of an exploration: parent run + per-lane child cards.'
      operationId: get_exploration_report_api_v1_explorations__run_id__report_get
      parameters:
      - in: path
        name: run_id
        required: true
        schema:
          format: uuid
          title: Run Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplorationRunReportResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get Exploration Report
      tags:
      - Explorations
components:
  schemas:
    TestRunConfig:
      description: Complete configuration for a test run.
      properties:
        cache_retry_mode:
          $ref: '#/components/schemas/CacheRetryMode'
          default: full_rerun
          description: Cache retry policy
        disable_grid:
          anyOf:
          - type: boolean
          - type: 'null'
          description: 'Admin-only: Disable grid preprocessing for grounding'
          title: Disable Grid
        disable_video_validation:
          default: false
          description: When true, skip the background video validation check on VALIDATION steps; the screenshot verdict alone decides validation outcomes.
          title: Disable Video Validation
          type: boolean
        execution_mode:
          $ref: '#/components/schemas/ExecutionModeConfig'
          default:
            enable_planning: false
            enable_reflection: true
            grounder_type: moondream3
            network_capture: true
            reflection_retries: 1
            retries: 1
            skip_app_install: false
          description: Execution mode configuration
        fail_fast:
          anyOf:
          - type: boolean
          - type: 'null'
          description: When true, the test halts immediately on the first failed validation or non-zero script exit code instead of continuing through remaining steps. Unset inherits the test-level value under a workflow override and otherwise behaves as false.
          title: Fail Fast
        fallback_trigger:
          $ref: '#/components/schemas/FallbackTrigger'
          default: final_fail
          description: When to trigger cache fallback
        llm_config:
          $ref: '#/components/schemas/LLMConfig'
          default:
            planning_model: gemini/gemini-3.8-flash
            primary_model: gemini/gemini-3.8-flash
            reflection_model: gemini/gemini-3.8-flash
          description: LLM model configuration
        run_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Run Id
      title: TestRunConfig
      type: object
    LLMConfig:
      description: Configuration for LLM models used in different stages.
      properties:
        planning_model:
          anyOf:
          - type: string
          - type: 'null'
          description: LLM model for planning, defaults to primary_model if not set
          title: Planning Model
        primary_model:
          default: gemini/gemini-3.8-flash
          description: Primary LLM model for step execution
          title: Primary Model
          type: string
        reflection_model:
          anyOf:
          - type: string
          - type: 'null'
          description: LLM model for reflection, defaults to primary_model if not set
          title: Reflection Model
      title: LLMConfig
      type: object
    ExplorationSessionResponse:
      properties:
        atlas_layer_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Atlas Layer Job Id
        id:
          title: Id
          type: string
        lane_index:
          title: Lane Index
          type: integer
        lane_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Lane Role
        report_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        session_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Status
        summary:
          additionalProperties: true
          title: Summary
          type: object
        workflow_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workflow Run Id
      required:
      - id
      - lane_index
      title: ExplorationSessionResponse
      type: object
    GrounderType:
      description: 'Grounder configuration that determines the grounding model.


        - MOONDREAM/MOONDREAM3/MOONDREAM_CUSTOM/MODAL_CUSTOM: Two-step grounding

        - AUTO: Use GROUNDER_TYPE env var to determine grounder

        - NULL: Skip grounding (for testing/debugging)'
      enum:
      - moondream
      - moondream3
      - moondream_custom
      - modal-custom
      - auto
      - 'null'
      title: GrounderType
      type: string
    CacheRetryMode:
      description: 'Cache retry policy for test execution.


        - NONE: No cache fallback, fail if cached steps fail

        - FULL_RERUN: If cached run fails, rerun entire test without cache'
      enum:
      - none
      - full_rerun
      title: CacheRetryMode
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    ExplorationRunReportResponse:
      properties:
        app_name:
          anyOf:
          - type: string
          - type: 'null'
          title: App Name
        app_platform:
          anyOf:
          - type: string
          - type: 'null'
          title: App Platform
        children:
          items:
            $ref: '#/components/schemas/ExplorationRunReportChild'
          title: Children
          type: array
        completed_children:
          default: 0
          title: Completed Children
          type: integer
        progress:
          default: 0.0
          title: Progress
          type: number
        run:
          $ref: '#/components/schemas/ExplorationRunResponse'
        total_children:
          default: 0
          title: Total Children
          type: integer
      required:
      - run
      title: ExplorationRunReportResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    CleanupLevel:
      description: Cleanup intensity level for AVD state reset between test runs.
      enum:
      - none
      - thorough
      - deep_clean
      title: CleanupLevel
      type: string
    ExplorationLaneConfig:
      properties:
        auth_instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth Instructions
        lane_index:
          title: Lane Index
          type: integer
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        seed_instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Seed Instructions
      required:
      - lane_index
      title: ExplorationLaneConfig
      type: object
    FallbackTrigger:
      description: 'When to trigger cache fallback.


        - FINAL_FAIL: Only trigger fallback if overall test fails'
      enum:
      - final_fail
      title: FallbackTrigger
      type: string
    ExplorationRunReportChild:
      description: A single exploration lane shaped as a run-report child card.
      properties:
        app_id:
          anyOf:
          - type: string
          - type: 'null'
          title: App Id
        app_name:
          anyOf:
          - type: string
          - type: 'null'
          title: App Name
        branch_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Branch Id
        branch_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Branch Name
        build_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Build Id
        build_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Build Version
        completed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Completed At
        device_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Device Model
        duration:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        lane_index:
          title: Lane Index
          type: integer
        lane_label:
          title: Lane Label
          type: string
        lane_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Lane Role
        platform:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
        report_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        step_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Step Count
        success:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Success
        task_id:
          title: Task Id
          type: string
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
        whep_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Whep Url
        workflow_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workflow Run Id
      required:
      - task_id
      - lane_index
      - lane_label
      title: ExplorationRunReportChild
      type: object
    ExplorationRunResponse:
      properties:
        app_id:
          title: App Id
          type: string
        atlas_status:
          title: Atlas Status
          type: string
        branch_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Branch Id
        branch_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Branch Name
        build_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Build Id
        build_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Build Version
        completed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Completed At
        config:
          additionalProperties: true
          title: Config
          type: object
        created_at:
          format: date-time
          title: Created At
          type: string
        customer_status:
          title: Customer Status
          type: string
        execution_status:
          title: Execution Status
          type: string
        findings:
          items:
            additionalProperties: true
            type: object
          title: Findings
          type: array
        id:
          title: Id
          type: string
        mode:
          title: Mode
          type: string
        sessions:
          items:
            $ref: '#/components/schemas/ExplorationSessionResponse'
          title: Sessions
          type: array
        summary:
          additionalProperties: true
          title: Summary
          type: object
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
        updated_at:
          format: date-time
          title: Updated At
          type: string
      required:
      - id
      - app_id
      - mode
      - execution_status
      - atlas_status
      - customer_status
      - created_at
      - updated_at
      title: ExplorationRunResponse
      type: object
    LocationConfig:
      description: GPS location configuration for simulator/emulator.
      properties:
        latitude:
          description: GPS latitude coordinate (-90 to 90)
          maximum: 90.0
          minimum: -90.0
          title: Latitude
          type: number
        longitude:
          description: GPS longitude coordinate (-180 to 180)
          maximum: 180.0
          minimum: -180.0
          title: Longitude
          type: number
      required:
      - latitude
      - longitude
      title: LocationConfig
      type: object
    BuildSelectionMode:
      enum:
      - inherit
      - latest
      - pinned
      - latest_all_branches
      title: BuildSelectionMode
      type: string
    ExplorationCancelResponse:
      properties:
        execution_status:
          title: Execution Status
          type: string
        hatchet_cancelled:
          title: Hatchet Cancelled
          type: boolean
        run_id:
          title: Run Id
          type: string
      required:
      - run_id
      - execution_status
      - hatchet_cancelled
      title: ExplorationCancelResponse
      type: object
    ExplorationLaunchRequest:
      properties:
        auth_instructions:
          anyOf:
          - maxLength: 4000
            type: string
          - type: 'null'
          title: Auth Instructions
        branch_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Branch Id
        branch_name:
          anyOf:
          - maxLength: 255
            minLength: 1
            type: string
          - type: 'null'
          title: Branch Name
        build_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Build Id
        build_selection:
          $ref: '#/components/schemas/BuildSelectionMode'
          default: inherit
        context_branch_name:
          anyOf:
          - maxLength: 4096
            type: string
          - type: 'null'
          title: Context Branch Name
        device_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Device Model
        env_vars:
          additionalProperties:
            type: string
          title: Env Vars
          type: object
        idle_timeout_seconds:
          anyOf:
          - maximum: 7200.0
            minimum: 60.0
            type: integer
          - type: 'null'
          default: 900
          title: Idle Timeout Seconds
        lane_count:
          default: 3
          maximum: 100.0
          minimum: 1.0
          title: Lane Count
          type: integer
        lanes:
          items:
            $ref: '#/components/schemas/ExplorationLaneConfig'
          title: Lanes
          type: array
        launch_env_var_ids:
          items:
            format: uuid
            type: string
          title: Launch Env Var Ids
          type: array
        max_duration_seconds:
          default: 1800
          maximum: 7200.0
          minimum: 60.0
          title: Max Duration Seconds
          type: integer
        max_turns:
          anyOf:
          - maximum: 50.0
            minimum: 1.0
            type: integer
          - type: 'null'
          title: Max Turns
        os_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Os Version
        pinned_build_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Pinned Build Id
        platform:
          default: ios
          title: Platform
          type: string
        run_config:
          anyOf:
          - $ref: '#/components/schemas/TestRunConfig'
          - type: 'null'
        seed_instructions:
          anyOf:
          - maxLength: 4000
            type: string
          - type: 'null'
          title: Seed Instructions
        swarm_strategy:
          anyOf:
          - type: string
          - type: 'null'
          default: balanced
          description: Swarm allocation strategy; roles are derived programmatically.
          title: Swarm Strategy
      title: ExplorationLaunchRequest
      type: object
    DeviceCleanupConfig:
      description: 'Configuration for AVD cleanup between test runs.


        Controls what gets reset when resetting device state between tests

        while keeping the emulator running.'
      properties:
        cleanup_level:
          $ref: '#/components/schemas/CleanupLevel'
          default: thorough
          description: 'Level of cleanup to perform (default: THOROUGH for maximum cleanup)'
        clear_app_data:
          default: true
          description: Clear app data and cache via pm clear
          title: Clear App Data
          type: boolean
        clear_browser_data:
          default: true
          description: Clear browsing data (history, cookies, cache) from all browsers
          title: Clear Browser Data
          type: boolean
        clear_clipboard:
          default: true
          description: Clear clipboard contents
          title: Clear Clipboard
          type: boolean
        clear_downloads:
          default: true
          description: Clear /sdcard/Download folder
          title: Clear Downloads
          type: boolean
        clear_notifications:
          default: true
          description: Clear all pending notifications from previous test sessions
          title: Clear Notifications
          type: boolean
        clear_recent_apps:
          default: false
          description: Clear recent apps list (requires root access, restarts framework). Expensive (~15-30s), broken on Play Store images. Auto-enabled for DEEP_CLEAN.
          title: Clear Recent Apps
          type: boolean
        clear_shared_storage:
          default: true
          description: Clear Pictures, DCIM, Movies, Music, Documents folders
          title: Clear Shared Storage
          type: boolean
        custom_paths_to_clear:
          description: Additional paths to clear on device
          items:
            type: string
          title: Custom Paths To Clear
          type: array
        kill_background_apps:
          default: true
          description: Kill all background applications
          title: Kill Background Apps
          type: boolean
        reset_system_ui:
          default: false
          description: Reset SystemUI state including wallpaper to defaults. Expensive (~2-3s). Auto-enabled for DEEP_CLEAN.
          title: Reset System Ui
          type: boolean
        revoke_permissions:
          default: true
          description: Revoke runtime permissions granted during test
          title: Revoke Permissions
          type: boolean
        uninstall_new_apps:
          default: true
          description: Uninstall apps that were installed during the test session
          title: Uninstall New Apps
          type: boolean
      title: DeviceCleanupConfig
      type: object
    ExplorationLaunchResponse:
      properties:
        report_url:
          title: Report Url
          type: string
        run:
          $ref: '#/components/schemas/ExplorationRunResponse'
      required:
      - run
      - report_url
      title: ExplorationLaunchResponse
      type: object
    ExecutionModeConfig:
      description: Configuration for execution modes and features.
      properties:
        cleanup_config:
          anyOf:
          - $ref: '#/components/schemas/DeviceCleanupConfig'
          - type: 'null'
          description: Configuration for AVD cleanup between test runs
        enable_planning:
          default: false
          description: Enable planning for complex steps
          title: Enable Planning
          type: boolean
        enable_reflection:
          default: true
          description: Enable reflection on failed steps
          title: Enable Reflection
          type: boolean
        grounder_type:
          anyOf:
          - $ref: '#/components/schemas/GrounderType'
          - type: 'null'
          default: moondream3
        initial_locale:
          anyOf:
          - type: string
          - type: 'null'
          description: Initial device locale identifier, for example 'en_US' or 'fr_FR'
          title: Initial Locale
        initial_location:
          anyOf:
          - $ref: '#/components/schemas/LocationConfig'
          - type: 'null'
          description: Initial GPS location to set when simulator boots
        initial_orientation:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Initial device orientation: ''portrait'' or ''landscape'''
          title: Initial Orientation
        network_capture:
          default: true
          description: Attach an in-process TLS-capture agent to the (debuggable) app under test to record decrypted HTTP traffic. On by default (no-op/graceful on non-debuggable apps or attach failure); set False to disable as a per-run kill switch.
          title: Network Capture
          type: boolean
        reflection_retries:
          default: 1
          description: Number of reflection retry attempts
          title: Reflection Retries
          type: integer
        retries:
          default: 1
          description: Number of retry attempts
          title: Retries
          type: integer
        skip_app_install:
          default: false
          description: Skip app installation during test execution
          title: Skip App Install
          type: boolean
      title: ExecutionModeConfig
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http