openapi: 3.0.3
info:
  title: Runloop agents Devbox-FileTools API
  version: '0.1'
  description: Register, version, and mount Agents — packaged agent definitions sourced from Git, npm, pip, or storage objects that can be installed on Devboxes for fast, reproducible agent execution.
  contact:
    name: Runloop AI Support
    url: https://runloop.ai
    email: support@runloop.ai
servers:
- url: https://api.runloop.ai
  description: Runloop API
  variables: {}
security:
- bearerAuth: []
tags:
- name: Devbox-FileTools
paths:
  /v1/devboxes/{id}/download_file:
    post:
      tags:
      - Devbox-FileTools
      summary: Download binary file contents from Devbox filesystem.
      description: Download file contents of any type (binary, text, etc) from a specified path on the Devbox.
      operationId: devboxDownloadFile
      parameters:
      - name: id
        in: path
        description: The Devbox ID.
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevboxDownloadFileParameters'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                format: binary
          headers:
            Content-Type:
              description: application/octet-stream
              required: true
              schema:
                type: string
            Content-Disposition:
              description: attachment
              required: true
              schema:
                type: string
        '404':
          description: Devbox not found.
      deprecated: false
  /v1/devboxes/{id}/read_file_contents:
    post:
      tags:
      - Devbox-FileTools
      summary: Read text file contents from Devbox filesystem.
      description: Read file contents from a file on a Devbox as a UTF-8. Note 'downloadFile' should be used for large files (greater than 100MB). Returns the file contents as a UTF-8 string.
      operationId: devboxReadFileContents
      parameters:
      - name: id
        in: path
        description: The Devbox ID.
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevboxReadFileParameters'
        required: false
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Devbox not found.
      deprecated: false
  /v1/devboxes/{id}/upload_file:
    post:
      tags:
      - Devbox-FileTools
      summary: Upload binary file contents to Devbox filesystem.
      description: Upload file contents of any type (binary, text, etc) to a Devbox. Note this API is suitable for large files (larger than 100MB) and efficiently uploads files via multipart form data.
      operationId: devboxUploadFile
      parameters:
      - name: id
        in: path
        description: The Devbox ID.
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FileUpload'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyRecord'
        '404':
          description: Devbox not found.
      deprecated: false
  /v1/devboxes/{id}/write_file_contents:
    post:
      tags:
      - Devbox-FileTools
      summary: Write text file contents to Devbox filesystem.
      description: Write UTF-8 string contents to a file at path on the Devbox. Note for large files (larger than 100MB), the upload_file endpoint must be used.
      operationId: devboxWriteFileContents
      parameters:
      - name: id
        in: path
        description: The Devbox ID.
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevboxWriteFileParameters'
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevboxExecutionDetailView'
        '404':
          description: Devbox not found.
      deprecated: false
components:
  schemas:
    DevboxWriteFileParameters:
      type: object
      additionalProperties: false
      properties:
        file_path:
          type: string
          description: The path to write the file to on the Devbox. Path is relative to user home directory.
        contents:
          type: string
          description: The UTF-8 string contents to write to the file.
      required:
      - file_path
      - contents
    FileUpload:
      type: object
      additionalProperties: false
      properties:
        file:
          type: string
          format: binary
        path:
          type: string
          description: The path to write the file to on the Devbox. Path is relative to user home directory.
      required:
      - path
    DevboxReadFileParameters:
      type: object
      additionalProperties: false
      properties:
        file_path:
          type: string
          description: The path on the Devbox filesystem to read the file from. Path is relative to user home directory.
      required:
      - file_path
    DevboxDownloadFileParameters:
      type: object
      additionalProperties: false
      properties:
        path:
          type: string
          description: The path on the Devbox filesystem to read the file from. Path is relative to user home directory.
      required:
      - path
    EmptyRecord:
      type: object
      additionalProperties: false
      properties: {}
    DevboxExecutionDetailView:
      type: object
      additionalProperties: false
      properties:
        devbox_id:
          type: string
          description: Devbox id where command was executed.
        stdout:
          type: string
          description: Standard out generated by command.
        stderr:
          type: string
          description: Standard error generated by command.
        exit_status:
          type: integer
          format: int32
          description: Exit status of command execution.
        shell_name:
          type: string
          nullable: true
          description: Shell name.
      required:
      - devbox_id
      - stdout
      - stderr
      - exit_status
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http