Kernel Browser Filesystem API

openapi: 3.2.0
info:
  description: Developer tools and cloud infrastructure for AI agents to use web browsers
  title: Kernel Browser Filesystem API
  version: 0.1.0
servers:
- description: API Server
  url: https://api.onkernel.com
security:
- bearerAuth: []
tags:
- description: Read, write, and manage files on the browser instance.
  name: Browser Filesystem
paths:
  /browsers/{id_or_name}/fs/create_directory:
    put:
      operationId: createDirectory
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectoryRequest'
        required: true
      responses:
        '201':
          description: Directory created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Create a new directory
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/delete_directory:
    put:
      operationId: deleteDirectory
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePathRequest'
        required: true
      responses:
        '200':
          description: Directory deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Delete a directory
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/delete_file:
    put:
      operationId: deleteFile
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePathRequest'
        required: true
      responses:
        '200':
          description: File deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Delete a file
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/download_dir_zip:
    get:
      description: Returns a ZIP file containing the contents of the specified directory.
      operationId: downloadDirZip
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - description: Absolute directory path to archive and download.
        in: query
        name: path
        required: true
        schema:
          pattern: ^/.*
          type: string
      responses:
        '200':
          content:
            application/zip:
              schema:
                format: binary
                type: string
          description: ZIP archive of the requested directory
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Download a directory as a ZIP archive
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/file_info:
    get:
      operationId: fileInfo
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - description: Absolute path of the file or directory.
        in: query
        name: path
        required: true
        schema:
          pattern: ^/.*
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileInfo'
          description: File information
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Get information about a file or directory
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/list_files:
    get:
      operationId: listFiles
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - description: Absolute directory path.
        in: query
        name: path
        required: true
        schema:
          pattern: ^/.*
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFiles'
          description: Directory listing
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: List files in a directory
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/move:
    put:
      operationId: movePath
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovePathRequest'
        required: true
      responses:
        '200':
          description: Move successful
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Move or rename a file or directory
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/read_file:
    get:
      operationId: readFile
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - description: Absolute file path to read.
        in: query
        name: path
        required: true
        schema:
          pattern: ^/.*
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: File read successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Read file contents
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/set_file_permissions:
    put:
      operationId: setFilePermissions
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetFilePermissionsRequest'
        required: true
      responses:
        '200':
          description: Permissions updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Set file or directory permissions/ownership
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/upload:
    post:
      description: Allows uploading single or multiple files to the remote filesystem.
      operationId: uploadFiles
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                files:
                  items:
                    properties:
                      dest_path:
                        description: Absolute destination path to write the file.
                        pattern: ^/.*
                        type: string
                      file:
                        format: binary
                        type: string
                    required:
                    - file
                    - dest_path
                    type: object
                  type: array
              required:
              - files
              type: object
        required: true
      responses:
        '201':
          description: Files uploaded successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Upload one or more files
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/upload_zip:
    post:
      description: Upload a zip file and extract its contents to the specified destination path.
      operationId: uploadZip
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                dest_path:
                  description: Absolute destination directory to extract the archive to.
                  pattern: ^/.*
                  type: string
                zip_file:
                  format: binary
                  type: string
              required:
              - zip_file
              - dest_path
              type: object
        required: true
      responses:
        '201':
          description: Zip uploaded and extracted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Upload a zip archive and extract it
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/watch:
    post:
      operationId: startFsWatch
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartFsWatchRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  watch_id:
                    description: Unique identifier for the directory watch
                    type: string
                type: object
          description: Watch started successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Watch a directory for changes
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/watch/{watch_id}:
    delete:
      operationId: stopFsWatch
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - in: path
        name: watch_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Watch stopped successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Stop watching a directory
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/watch/{watch_id}/events:
    get:
      operationId: streamFsEvents
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - in: path
        name: watch_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/FileSystemEvent'
          description: SSE stream of filesystem events
          headers:
            X-SSE-Content-Type:
              description: Media type of SSE data events (application/json)
              schema:
                const: application/json
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Stream filesystem events for a watch
      tags:
      - Browser Filesystem
  /browsers/{id_or_name}/fs/write_file:
    put:
      operationId: writeFile
      parameters:
      - description: Browser session ID or name
        example: htzv5orfit78e1m2biiifpbv
        in: path
        name: id_or_name
        required: true
        schema:
          type: string
      - description: Destination absolute file path.
        in: query
        name: path
        required: true
        schema:
          pattern: ^/.*
          type: string
      - description: Optional file mode (octal string, e.g. 644). Defaults to 644.
        in: query
        name: mode
        required: false
        schema:
          pattern: ^[0-7]{3,4}$
          type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        required: true
      responses:
        '201':
          description: File written successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        default:
          $ref: '#/components/responses/BrowserProxyError'
      security:
      - bearerAuth: []
      summary: Write or create a file
      tags:
      - Browser Filesystem
components:
  schemas:
    SetFilePermissionsRequest:
      additionalProperties: false
      properties:
        group:
          description: New group name or GID.
          type: string
        mode:
          description: File mode bits (octal string, e.g. 644).
          pattern: ^[0-7]{3,4}$
          type: string
        owner:
          description: New owner username or UID.
          type: string
        path:
          description: Absolute path whose permissions are to be changed.
          pattern: ^/.*
          type: string
      required:
      - path
      - mode
      type: object
    CreateDirectoryRequest:
      additionalProperties: false
      properties:
        mode:
          description: Optional directory mode (octal string, e.g. 755). Defaults to 755.
          pattern: ^[0-7]{3,4}$
          type: string
        path:
          description: Absolute directory path to create.
          pattern: ^/.*
          type: string
      required:
      - path
      type: object
    ListFiles:
      description: Array of file or directory information entries.
      items:
        $ref: '#/components/schemas/FileInfo'
      type: array
    ErrorDetail:
      properties:
        code:
          description: Lower-level error code providing more specific detail
          example: invalid_input
          type: string
        message:
          description: Further detail about the error
          example: Provided version string is not semver compliant
          type: string
      type: object
    MovePathRequest:
      additionalProperties: false
      properties:
        dest_path:
          description: Absolute destination path.
          pattern: ^/.*
          type: string
        src_path:
          description: Absolute source path.
          pattern: ^/.*
          type: string
      required:
      - src_path
      - dest_path
      type: object
    Error:
      properties:
        code:
          description: Application-specific error code (machine-readable)
          example: bad_request
          type: string
        details:
          description: Additional error details (for multiple errors)
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        inner_error:
          $ref: '#/components/schemas/ErrorDetail'
        message:
          description: Human-readable error description for debugging
          example: 'Missing required field: app_name'
          type: string
      required:
      - code
      - message
      type: object
    FileSystemEvent:
      description: Filesystem change event.
      properties:
        is_dir:
          description: Whether the affected path is a directory.
          type: boolean
        name:
          description: Base name of the file or directory affected.
          type: string
        path:
          description: Absolute path of the file or directory.
          type: string
        type:
          description: Event type.
          enum:
          - CREATE
          - WRITE
          - DELETE
          - RENAME
          type: string
      required:
      - type
      - path
      type: object
    DeletePathRequest:
      additionalProperties: false
      properties:
        path:
          description: Absolute path to delete.
          pattern: ^/.*
          type: string
      required:
      - path
      type: object
    FileInfo:
      properties:
        is_dir:
          description: Whether the path is a directory.
          type: boolean
        mod_time:
          description: Last modification time.
          format: date-time
          type: string
        mode:
          description: File mode bits (e.g., "drwxr-xr-x" or "-rw-r--r--").
          type: string
        name:
          description: Base name of the file or directory.
          type: string
        path:
          description: Absolute path.
          type: string
        size_bytes:
          description: Size in bytes. 0 for directories.
          type: integer
      required:
      - name
      - path
      - size_bytes
      - is_dir
      - mod_time
      - mode
      type: object
    InstanceProxyError:
      properties:
        code:
          $ref: '#/components/schemas/InstanceProxyErrorCode'
        message:
          description: Human-readable error description for debugging
          type: string
      required:
      - code
      - message
      type: object
    StartFsWatchRequest:
      additionalProperties: false
      properties:
        path:
          description: Directory to watch.
          type: string
        recursive:
          default: false
          description: Whether to watch recursively.
          type: boolean
      required:
      - path
      type: object
    InstanceProxyErrorCode:
      description: Canonical error code returned by browser instance API proxy routes
      enum:
      - invalid_request
      - unauthorized
      - forbidden
      - session_not_leased
      - not_found
      - conflict
      - session_gone
      - rate_limit_exceeded
      - internal_error
      - browser_unavailable
      type: string
  responses:
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad Request – invalid input
    InternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal Server Error
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Forbidden – insufficient permissions or plan
    BrowserProxyError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InstanceProxyError'
      description: Error returned by the browser or its proxy
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
x-service-info:
  categories:
  - browsers
  docs:
    apiReference: https://www.kernel.sh/docs
    homepage: https://www.kernel.sh
    llms: https://api.onkernel.com/llms.txt
x-provenance:
  method: harvested
  publisher: Kernel
  source: https://api.onkernel.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)