Revyl Recording Compilation API

openapi: 3.2.0
info:
  description: Revyl API
  title: Revyl Recording Compilation API
  version: 1.0.0
servers:
- description: Production
  url: https://backend.revyl.ai
tags:
- name: Recording Compilation
paths:
  /api/v1/recordings/compile:
    post:
      description: Build a compile plan and launch the compilation workflow.
      operationId: start_compile_api_v1_recordings_compile_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompileRecordingRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompileRecordingStartResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Start Compile
      tags:
      - Recording Compilation
  /api/v1/recordings/compile/{job_id}:
    get:
      description: Poll the status of a compile job.
      operationId: get_compile_status_api_v1_recordings_compile__job_id__get
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          title: Job Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompileRecordingStatusResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Get Compile Status
      tags:
      - Recording Compilation
components:
  schemas:
    CompiledIntentStep:
      description: One natural-language test step produced by the final merge pass.
      properties:
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          description: Model confidence 0-1 if available
          title: Confidence
        manual_subtype:
          anyOf:
          - type: string
          - type: 'null'
          description: 'For manual steps: go_home, open_app, kill_app, back, set_location, set_orientation, set_appearance, set_font_size, wait, navigate'
          title: Manual Subtype
        source_action_ranges:
          description: Which raw actions this step covers
          items:
            $ref: '#/components/schemas/ActionRange'
          title: Source Action Ranges
          type: array
        step_description:
          description: Natural language instruction an agent can follow to reproduce the action
          title: Step Description
          type: string
        step_type:
          description: instruction, validation, or manual
          title: Step Type
          type: string
      required:
      - step_type
      - step_description
      title: CompiledIntentStep
      type: object
    CompileResult:
      description: Final output of a compile job, stored on the job row.
      properties:
        blocks:
          description: Editor Block[] dicts ready for the frontend
          items:
            additionalProperties: true
            type: object
          title: Blocks
          type: array
        compiled_steps:
          description: Ordered intent steps
          items:
            $ref: '#/components/schemas/CompiledIntentStep'
          title: Compiled Steps
          type: array
        suggested_title:
          anyOf:
          - type: string
          - type: 'null'
          description: Short LLM-generated title with a 4-hex suffix for uniqueness
          title: Suggested Title
        total_actions_compiled:
          default: 0
          title: Total Actions Compiled
          type: integer
        total_chunks_processed:
          default: 0
          title: Total Chunks Processed
          type: integer
        warnings:
          description: Any quality or ambiguity warnings from compilation
          items:
            type: string
          title: Warnings
          type: array
        yaml:
          default: ''
          description: YAML string of the compiled test blocks
          title: Yaml
          type: string
      title: CompileResult
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ActionRange:
      description: A contiguous range of source action indices.
      properties:
        end:
          description: Inclusive end action_index
          title: End
          type: integer
        start:
          description: Inclusive start action_index
          title: Start
          type: integer
      required:
      - start
      - end
      title: ActionRange
      type: object
    CompileRecordingStartResponse:
      description: Response from POST /recordings/compile.
      properties:
        job_id:
          description: UUID of the compile job
          title: Job Id
          type: string
        status:
          default: queued
          title: Status
          type: string
      required:
      - job_id
      title: CompileRecordingStartResponse
      type: object
    CompileJobStatus:
      description: Lifecycle states for a recording compile job.
      enum:
      - queued
      - preparing
      - summarizing
      - merging
      - formatting
      - completed
      - failed
      title: CompileJobStatus
      type: string
    CompileJobProgress:
      description: Progress metadata returned by the status endpoint.
      properties:
        completed_chunk_indices:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          description: Which specific chunk indices have completed
          title: Completed Chunk Indices
        completed_chunks:
          default: 0
          title: Completed Chunks
          type: integer
        message:
          anyOf:
          - type: string
          - type: 'null'
          description: Human-readable progress note
          title: Message
        stage:
          $ref: '#/components/schemas/CompileJobStatus'
          default: queued
          description: Current stage of the pipeline
        total_chunks:
          default: 0
          title: Total Chunks
          type: integer
      title: CompileJobProgress
      type: object
    CompileSourceType:
      description: How the compile was triggered.
      enum:
      - recording
      - session
      title: CompileSourceType
      type: string
    CompileRecordingRequest:
      description: Request body for POST /recordings/compile.
      properties:
        interval_end:
          anyOf:
          - type: integer
          - type: 'null'
          description: End action index (inclusive)
          title: Interval End
        interval_end_time:
          anyOf:
          - type: number
          - type: 'null'
          description: End time in seconds from recording start
          title: Interval End Time
        interval_start:
          anyOf:
          - type: integer
          - type: 'null'
          description: Start action index (inclusive)
          title: Interval Start
        interval_start_time:
          anyOf:
          - type: number
          - type: 'null'
          description: Start time in seconds from recording start
          title: Interval Start Time
        source_id:
          description: session_id or report_id depending on source_type
          title: Source Id
          type: string
        source_type:
          $ref: '#/components/schemas/CompileSourceType'
          description: recording or session
        user_feedback:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional user instructions for how to adjust compilation (e.g. 'more validations', 'less verbose')
          title: User Feedback
      required:
      - source_type
      - source_id
      title: CompileRecordingRequest
      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
    CompileRecordingStatusResponse:
      description: Response from GET /recordings/compile/{job_id}.
      properties:
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        job_id:
          title: Job Id
          type: string
        progress:
          anyOf:
          - $ref: '#/components/schemas/CompileJobProgress'
          - type: 'null'
        result:
          anyOf:
          - $ref: '#/components/schemas/CompileResult'
          - type: 'null'
        status:
          title: Status
          type: string
      required:
      - job_id
      - status
      title: CompileRecordingStatusResponse
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http