Revyl Reports V3 API

openapi: 3.2.0
info:
  description: Revyl API
  title: Revyl Reports V3 API
  version: 1.0.0
servers:
- description: Production
  url: https://backend.revyl.ai
tags:
- name: Reports V3
paths:
  /api/v1/reports-v3/reports/by-execution/{execution_id}/context:
    get:
      description: 'Get a high-context report by execution_id for CLI JSON and coding-agent use.


        This stays close to the raw report payload, but adds backend-derived

        rendering/media fields so downstream consumers do not need to reconstruct

        report semantics client-side.'
      operationId: get_report_context_by_execution_api_v1_reports_v3_reports_by_execution__execution_id__context_get
      parameters:
      - in: path
        name: execution_id
        required: true
        schema:
          title: Execution Id
          type: string
      - in: query
        name: include_steps
        required: false
        schema:
          default: true
          title: Include Steps
          type: boolean
      - in: query
        name: include_actions
        required: false
        schema:
          default: true
          title: Include Actions
          type: boolean
      - in: query
        name: include_llm_calls
        required: false
        schema:
          default: true
          title: Include Llm Calls
          type: boolean
      - description: Public share token for unauthenticated access
        in: query
        name: token
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Public share token for unauthenticated access
          title: Token
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportContextResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get Report Context By Execution
      tags:
      - Reports V3
  /api/v1/reports-v3/reports/by-session/{session_id}/context:
    get:
      description: 'Get a high-context report by device session_id for CLI/MCP consumption.


        Same enrichment as the by-execution context endpoint but keyed by

        device session rather than test execution.


        Args:

        session_id: The device_sessions UUID.

        include_steps: Whether to include steps (default: True).

        include_actions: Whether to include actions within steps (default: True).

        include_llm_calls: Whether to include LLM call details (default: True).'
      operationId: get_report_context_by_session_api_v1_reports_v3_reports_by_session__session_id__context_get
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          title: Session Id
          type: string
      - in: query
        name: include_steps
        required: false
        schema:
          default: true
          title: Include Steps
          type: boolean
      - in: query
        name: include_actions
        required: false
        schema:
          default: true
          title: Include Actions
          type: boolean
      - in: query
        name: include_llm_calls
        required: false
        schema:
          default: true
          title: Include Llm Calls
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportContextResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get Report Context By Session
      tags:
      - Reports V3
  /api/v1/reports-v3/reports/{report_id}/device-logs:
    get:
      description: 'Get a presigned download URL for device logs (logcat/iOS system logs).


        Supports both authenticated and public (token-based) access.

        Returns a presigned S3 URL that expires in 1 hour.'
      operationId: get_device_logs_download_url_api_v1_reports_v3_reports__report_id__device_logs_get
      parameters:
      - in: path
        name: report_id
        required: true
        schema:
          title: Report Id
          type: string
      - description: Public share token for unauthenticated access
        in: query
        name: token
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Public share token for unauthenticated access
          title: Token
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceLogsDownloadResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get Device Logs Download Url
      tags:
      - Reports V3
components:
  schemas:
    DeviceMetadata:
      description: 'Device metadata captured at runtime for accurate coordinate scaling.


        This schema is still actively used and stored in the reports.device_metadata

        column in the database.'
      properties:
        device_type:
          anyOf:
          - type: string
          - type: 'null'
          description: Device type/model (e.g., 'iPhone 16', 'Pixel 7')
          title: Device Type
        height:
          description: Device screen height in logical pixels
          title: Height
          type: integer
        platform:
          anyOf:
          - type: string
          - type: 'null'
          description: Platform name ('ios' or 'android')
          title: Platform
        runtime:
          anyOf:
          - type: string
          - type: 'null'
          description: Device runtime version (e.g., 'iOS 18.5', 'Android 34')
          title: Runtime
        width:
          description: Device screen width in logical pixels
          title: Width
          type: integer
      required:
      - width
      - height
      title: DeviceMetadata
      type: object
    LaunchConfigurationKind:
      description: Stored app-launch configuration payload type.
      enum:
      - key_value
      - ios_arguments
      title: LaunchConfigurationKind
      type: string
    LaunchEnvVarSnapshotEntry:
      description: Sanitized immutable launch-variable fact stored on a device session.
      properties:
        arguments:
          anyOf:
          - items:
              minLength: 1
              pattern: ^[^\x00]+$
              type: string
            type: array
          - type: 'null'
          title: Arguments
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        is_secret:
          default: true
          title: Is Secret
          type: boolean
        key:
          title: Key
          type: string
        kind:
          $ref: '#/components/schemas/LaunchConfigurationKind'
          default: key_value
        value:
          anyOf:
          - type: string
          - type: 'null'
          title: Value
      required:
      - key
      title: LaunchEnvVarSnapshotEntry
      type: object
    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
    LaunchFailureSummary:
      properties:
        error:
          title: Error
          type: string
        error_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Type
        launch_failure:
          $ref: '#/components/schemas/LaunchFailureDiagnosis'
        stage:
          const: initial_setup
          title: Stage
          type: string
      required:
      - error
      - stage
      - launch_failure
      title: LaunchFailureSummary
      type: object
    IOSRuntimeCheckerFrame:
      additionalProperties: false
      properties:
        app_image:
          anyOf:
          - $ref: '#/components/schemas/IOSCrashAppImage'
          - type: 'null'
        image:
          maxLength: 256
          title: Image
          type: string
        index:
          maximum: 10000.0
          minimum: 0.0
          title: Index
          type: integer
        location:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          title: Location
        symbol:
          maxLength: 2048
          title: Symbol
          type: string
      required:
      - index
      - image
      - symbol
      title: IOSRuntimeCheckerFrame
      type: object
    LaunchFailureCategory:
      enum:
      - app_build
      - infrastructure
      - unknown
      title: LaunchFailureCategory
      type: string
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    IOSRuntimeCheckerStack:
      additionalProperties: false
      properties:
        frames:
          items:
            $ref: '#/components/schemas/IOSRuntimeCheckerFrame'
          maxItems: 32
          title: Frames
          type: array
        title:
          maxLength: 512
          title: Title
          type: string
      required:
      - title
      - frames
      title: IOSRuntimeCheckerStack
      type: object
    ReportContextResponse:
      description: Canonical high-context report payload for CLI JSON consumption.
      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_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Build Version
        completed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Completed At
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        device_metadata:
          anyOf:
          - $ref: '#/components/schemas/DeviceMetadata'
          - type: 'null'
        device_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Device Model
        device_state_partial:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Device State Partial
        device_state_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Device State Url
        duration_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Duration Seconds
        effective_failed_steps:
          default: 0
          title: Effective Failed Steps
          type: integer
        effective_passed_steps:
          default: 0
          title: Effective Passed Steps
          type: integer
        effective_pending_steps:
          default: 0
          title: Effective Pending Steps
          type: integer
        effective_running_steps:
          default: 0
          title: Effective Running Steps
          type: integer
        effective_warning_steps:
          default: 0
          title: Effective Warning Steps
          type: integer
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        error_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Type
        execution_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Execution Id
        failed_steps:
          default: 0
          title: Failed Steps
          type: integer
        hardware_metrics_partial:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Hardware Metrics Partial
        hardware_metrics_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Hardware Metrics Url
        id:
          title: Id
          type: string
        launch_env_var_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Launch Env Var Ids
        launch_env_var_keys:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Launch Env Var Keys
        launch_env_var_snapshot:
          anyOf:
          - items:
              $ref: '#/components/schemas/LaunchEnvVarSnapshotEntry'
            type: array
          - type: 'null'
          title: Launch Env Var Snapshot
        locale:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
        network_requests_partial:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Network Requests Partial
        network_requests_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Network Requests Url
        org_id:
          title: Org Id
          type: string
        os_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Os Version
        passed_steps:
          default: 0
          title: Passed Steps
          type: integer
        perfetto_trace_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Perfetto Trace Url
        platform:
          anyOf:
          - type: string
          - type: 'null'
          title: Platform
        report_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Url
        resolved_build_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolved Build Id
        runtime_checker_findings:
          anyOf:
          - items:
              $ref: '#/components/schemas/IOSRuntimeCheckerFindingSummary'
            type: array
          - type: 'null'
          title: Runtime Checker Findings
        screen_height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Screen Height
        screen_width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Screen Width
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        session_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Status
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        steps:
          anyOf:
          - items:
              $ref: '#/components/schemas/ReportContextStepResponse'
            type: array
          - type: 'null'
          title: Steps
        success:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Success
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
        test_goal_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Test Goal Summary
        test_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Test Id
        test_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Test Name
        test_version_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Test Version Id
        test_version_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Test Version Number
        tldr:
          anyOf:
          - $ref: '#/components/schemas/TLDROutput'
          - $ref: '#/components/schemas/LaunchFailureSummary'
          - type: 'null'
          title: Tldr
        total_steps:
          default: 0
          title: Total Steps
          type: integer
        total_validations:
          default: 0
          title: Total Validations
          type: integer
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
        validations_passed:
          default: 0
          title: Validations Passed
          type: integer
        video_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Video Url
        warning_steps:
          default: 0
          title: Warning Steps
          type: integer
        whep_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Whep Url
        workflow_execution_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workflow Execution Id
      required:
      - id
      - org_id
      title: ReportContextResponse
      type: object
    IOSRuntimeCheckerKind:
      enum:
      - core_data_queue_violation
      - unclassified_app_crash
      - tsan_data_race
      - tsan_swift_access_race
      - tsan_other
      - main_thread_checker
      - address_sanitizer
      - undefined_behavior_sanitizer
      title: IOSRuntimeCheckerKind
      type: string
    TLDRKeyMoment:
      description: Key moment extracted from test execution
      properties:
        description:
          title: Description
          type: string
        importance:
          title: Importance
          type: string
        step_reference:
          title: Step Reference
          type: string
      required:
      - step_reference
      - description
      - importance
      title: TLDRKeyMoment
      type: object
    IOSRuntimeCheckerFindingSummary:
      additionalProperties: false
      description: A deduplicated checker report without its raw report text.
      properties:
        dedup_key:
          pattern: ^[0-9a-f]{16}$
          title: Dedup Key
          type: string
        first_observed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: First Observed At
        kind:
          $ref: '#/components/schemas/IOSRuntimeCheckerKind'
        last_observed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Last Observed At
        location:
          anyOf:
          - maxLength: 512
            type: string
          - type: 'null'
          title: Location
        occurrences:
          maximum: 1000000.0
          minimum: 1.0
          title: Occurrences
          type: integer
        process_ids:
          items:
            type: integer
          maxItems: 10
          title: Process Ids
          type: array
        stacks:
          items:
            $ref: '#/components/schemas/IOSRuntimeCheckerStack'
          maxItems: 4
          title: Stacks
          type: array
        summary:
          anyOf:
          - maxLength: 1024
            type: string
          - type: 'null'
          title: Summary
        title:
          maxLength: 512
          title: Title
          type: string
      required:
      - kind
      - title
      - dedup_key
      - occurrences
      - process_ids
      - stacks
      title: IOSRuntimeCheckerFindingSummary
      type: object
    ReportContextActionResponse:
      description: High-context action payload for CLI/agent report consumption.
      properties:
        action_index:
          title: Action Index
          type: integer
        action_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Action Type
        agent_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Description
        completed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Completed At
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        is_terminal:
          default: false
          title: Is Terminal
          type: boolean
        llm_call:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Llm Call
        llm_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Llm Call Id
        reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning
        reflection_decision:
          anyOf:
          - type: string
          - type: 'null'
          title: Reflection Decision
        reflection_llm_call:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Reflection Llm Call
        reflection_llm_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Reflection Llm Call Id
        reflection_reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Reflection Reasoning
        reflection_suggestion:
          anyOf:
          - type: string
          - type: 'null'
          title: Reflection Suggestion
        screenshot_after_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Screenshot After Url
        screenshot_before_clean_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Screenshot Before Clean Url
        screenshot_before_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Screenshot Before Url
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        step_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Id
        type_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Type Data
        video_timestamp_end:
          anyOf:
          - type: number
          - type: 'null'
          title: Video Timestamp End
        video_timestamp_start:
          anyOf:
          - type: number
          - type: 'null'
          title: Video Timestamp Start
      required:
      - action_index
      title: ReportContextActionResponse
      type: object
    IOSCrashAppImage:
      additionalProperties: false
      description: Customer binary identity and relative instruction offset for symbolication.
      properties:
        architecture:
          anyOf:
          - enum:
            - arm64
            - arm64e
            - x86_64
            - x86_64h
            - arm64_32
            - armv7
            - armv7s
            - i386
            type: string
          - type: 'null'
          title: Architecture
        name:
          maxLength: 256
          pattern: ^[A-Za-z0-9_][A-Za-z0-9_. -]{0,255}$
          title: Name
          type: string
        offset_bytes:
          anyOf:
          - maximum: 9007199254740991.0
            minimum: 0.0
            type: integer
          - type: 'null'
          format: int64
          title: Offset Bytes
        uuid:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Uuid
      required:
      - name
      title: IOSCrashAppImage
      type: object
    LaunchRuntimeProbe:
      enum:
      - not_run
      - passed
      - failed
      - unavailable
      title: LaunchRuntimeProbe
      type: string
    DeviceLogsDownloadResponse:
      description: Response model for device logs download URL.
      properties:
        compressed:
          title: Compressed
          type: boolean
        download_url:
          title: Download Url
          type: string
        file_size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: File Size Bytes
        filename:
          title: Filename
          type: string
        partial:
          default: false
          title: Partial
          type: boolean
      required:
      - download_url
      - filename
      - compressed
      title: DeviceLogsDownloadResponse
      type: object
    TLDROutput:
      description: TLDR output with structured citations
      properties:
        insights:
          items:
            type: string
          title: Insights
          type: array
        key_moments:
          items:
            $ref: '#/components/schemas/TLDRKeyMoment'
          title: Key Moments
          type: array
        llm_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Llm Metadata
        test_case:
          title: Test Case
          type: string
      required:
      - test_case
      - key_moments
      - insights
      title: TLDROutput
      type: object
    ReportContextStepResponse:
      description: High-context step payload for CLI/agent report consumption.
      properties:
        actions:
          default: []
          items:
            $ref: '#/components/schemas/ReportContextActionResponse'
          title: Actions
          type: array
        completed_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Completed At
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        effective_status:
          default: pending
          title: Effective Status
          type: string
        effective_status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Effective Status Reason
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
        execution_order:
          title: Execution Order
          type: integer
        id:
          title: Id
          type: string
        llm_call:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Llm Call
        llm_call_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Llm Call Id
        node_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Node Id
        parent_step_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Step Id
        report_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Report Id
        source_module_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Module Id
        source_module_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Module Name
        started_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Started At
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        status_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Reason
        step_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Description
        step_type:
          title: Step Type
          type: string
        success:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Success
        type_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Type Data
        validation_reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Validation Reasoning
        validation_result:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Validation Result
        video_timestamp_end:
          anyOf:
          - type: number
          - type: 'null'
          title: Video Timestamp End
        video_timestamp_start:
          anyOf:
          - type: number
          - type: 'null'
          title: Video Timestamp Start
      required:
      - id
      - execution_order
      - step_type
      title: ReportContextStepResponse
      type: object
    LaunchCrashEvidence:
      enum:
      - not_checked
      - app_code
      - instrumentation
      - inconclusive
      - not_found
      - unavailable
      title: LaunchCrashEvidence
      type: string
    LaunchFailureDiagnosis:
      additionalProperties: false
      properties:
        category:
          $ref: '#/components/schemas/LaunchFailureCategory'
          default: unknown
        crash_evidence:
          $ref: '#/components/schemas/LaunchCrashEvidence'
          default: not_checked
        runtime_probe:
          $ref: '#/components/schemas/LaunchRuntimeProbe'
          default: not_run
      title: LaunchFailureDiagnosis
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http