openapi: 3.1.0
info:
  title: IdeGYM Server API
  description: >-
    In-pod FastAPI server exposing tools (bash, file ops) and reward endpoints.
    Mounted under the /api prefix in the running container.
  version: 1.0.0
paths:
  /api/tools/bash:
    post:
      summary: Execute Bash Script
      operationId: execute_bash_script_api_tools_bash_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BashCommandRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/file/create:
    post:
      summary: Create File
      operationId: create_file_api_tools_file_create_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFileRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/file/edit:
    post:
      summary: Replace Lines
      operationId: replace_lines_api_tools_file_edit_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditFileRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/file/patch:
    post:
      summary: Patch File
      operationId: patch_file_api_tools_file_patch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFileRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/file/upload:
    post:
      summary: Upload File Chunk
      description: >-
        Write one base64 chunk into a file, so binary survives the JSON
        forwarding path.
      operationId: upload_file_chunk_api_tools_file_upload_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadFileChunkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadFileChunkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/tools/file/download:
    post:
      summary: Download File Chunk
      description: >-
        Read one base64 chunk of a file, so binary survives the JSON forwarding
        path.
      operationId: download_file_chunk_api_tools_file_download_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadFileChunkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadFileChunkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/rewards/compilation:
    post:
      summary: Compilation Reward
      operationId: compilation_reward_api_rewards_compilation_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompilationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/rewards/setup:
    post:
      summary: Setup Reward
      operationId: setup_reward_api_rewards_setup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/rewards/test:
    post:
      summary: Unit Test Reward
      operationId: unit_test_reward_api_rewards_test_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BashCommandRequest:
      properties:
        command:
          type: string
          title: Command
          description: Command to execute as a bash script
        cwd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cwd
          description: >-
            Working directory for the command. Defaults to the server's project
            directory. A relative path is resolved against it.
          examples:
            - /home/appuser/work
            - src
        env:
          additionalProperties:
            type: string
          type: object
          title: Env
          description: >-
            Environment variables added to the command's environment, overriding
            inherited ones. Prefer this over writing 'export' lines into the
            script: the values never enter the command text, so they are not
            logged with it.
          examples:
            - CI: '1'
        user:
          anyOf:
            - type: string
            - type: 'null'
          title: User
          description: >-
            Run the command as this user. Needs the server to run as root or to
            have passwordless sudo, as the server image does; leave unset to run
            as the server's own user.
          examples:
            - devuser
        timeout:
          type: number
          title: Timeout
          description: Timeout for the command execution in seconds
          default: 600
        graceful_termination_timeout:
          type: number
          title: Graceful Termination Timeout
          description: Timeout in seconds for graceful process termination
          default: 2
        max_output_bytes:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Output Bytes
          description: >-
            Maximum retained bytes for each output stream; null retains complete
            output
          default: 1048576
        strip_output:
          type: boolean
          title: Strip Output
          description: >-
            Trim leading and trailing whitespace from stdout and stderr. Off by
            default so that output is byte-for-byte what the command wrote;
            undecodable bytes are still replaced.
          default: false
      type: object
      required:
        - command
      title: BashCommandRequest
    CompilationRequest:
      properties:
        compilation_script:
          type: string
          title: Compilation Script
          default: ./gradlew assemble
        timeout:
          type: number
          title: Timeout
          description: Timeout for the compilation in seconds
          default: 600
        graceful_termination_timeout:
          type: number
          title: Graceful Termination Timeout
          description: Timeout in seconds for graceful process termination
          default: 2
      type: object
      title: CompilationRequest
    CreateFileRequest:
      properties:
        file_path:
          type: string
          title: File Path
        content:
          type: string
          title: Content
      type: object
      required:
        - file_path
        - content
      title: CreateFileRequest
    DownloadFileChunkRequest:
      properties:
        file_path:
          type: string
          title: File Path
        offset:
          type: integer
          minimum: 0
          title: Offset
          description: Byte offset in the file to read from
          default: 0
        length:
          type: integer
          minimum: 1
          title: Length
          description: Maximum number of raw bytes to read
          default: 1048576
      type: object
      required:
        - file_path
      title: DownloadFileChunkRequest
    DownloadFileChunkResponse:
      properties:
        file_path:
          type: string
          title: File Path
        offset:
          type: integer
          title: Offset
        content_base64:
          type: string
          title: Content Base64
          description: Base64-encoded bytes read at 'offset'
        bytes_read:
          type: integer
          title: Bytes Read
        size:
          type: integer
          title: Size
          description: Total size of the file
        eof:
          type: boolean
          title: Eof
          description: True when this chunk reaches the end of the file
      type: object
      required:
        - file_path
        - offset
        - content_base64
        - bytes_read
        - size
        - eof
      title: DownloadFileChunkResponse
    EditFileRequest:
      properties:
        file_path:
          type: string
          title: File Path
        start_line:
          type: integer
          minimum: 0
          title: Start Line
        end_line:
          type: integer
          minimum: 0
          title: End Line
        new_content:
          type: string
          title: New Content
      type: object
      required:
        - file_path
        - start_line
        - end_line
        - new_content
      title: EditFileRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PatchFileRequest:
      properties:
        file_path:
          type: string
          title: File Path
        patch:
          type: string
          title: Patch
      type: object
      required:
        - file_path
        - patch
      title: PatchFileRequest
      description: Applies a unified diff patch generated by `diff_patch.compute_diff`.
    SetupRequest:
      properties:
        setup_check_script:
          type: string
          title: Setup Check Script
          default: 'true'
        timeout:
          type: number
          title: Timeout
          description: Timeout for the setup in seconds
          default: 600
        graceful_termination_timeout:
          type: number
          title: Graceful Termination Timeout
          description: Timeout in seconds for graceful process termination
          default: 2
      type: object
      title: SetupRequest
    TestRequest:
      properties:
        test_script:
          type: string
          title: Test Script
          default: python -m pytest --junitxml=test-results.xml
        timeout:
          type: number
          title: Timeout
          description: Timeout for the test in seconds
          default: 600
        graceful_termination_timeout:
          type: number
          title: Graceful Termination Timeout
          description: Timeout in seconds for graceful process termination
          default: 2
      type: object
      title: TestRequest
    UploadFileChunkRequest:
      properties:
        file_path:
          type: string
          title: File Path
        content_base64:
          type: string
          title: Content Base64
          description: Base64-encoded bytes to write at 'offset'
        offset:
          type: integer
          minimum: 0
          title: Offset
          description: Byte offset in the file at which to write this chunk
          default: 0
        truncate:
          type: boolean
          title: Truncate
          description: >-
            Cut the file off at the end of this chunk once it is written, so a
            re-upload cannot leave the tail of a longer previous file behind.
            Set false for out-of-order writes.
          default: true
      type: object
      required:
        - file_path
        - content_base64
      title: UploadFileChunkRequest
      description: >-
        One chunk of a binary upload.


        Chunks travel as base64 inside the ordinary JSON forwarding path, which
        is what makes them

        binary-safe: the orchestrator stores and replays a forwarded request as
        JSON text, so raw

        bytes would not survive the round trip.
    UploadFileChunkResponse:
      properties:
        file_path:
          type: string
          title: File Path
        bytes_written:
          type: integer
          title: Bytes Written
        size:
          type: integer
          title: Size
          description: Size of the file after the write
      type: object
      required:
        - file_path
        - bytes_written
        - size
      title: UploadFileChunkResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError