Skip to main content

openhands.server.routes.files

list_files​

@app.get('/list-files')
async def list_files(request: Request,
                     conversation_id: str,
                     path: str | None = None)

List files in the specified path.

This function retrieves a list of files from the agent's runtime file store, excluding certain system and hidden files/directories.

To list files:

curl http://localhost:3000/api/list-files

Arguments:

  • request Request - The incoming request object.
  • path str, optional - The path to list files from. Defaults to None.

Returns:

  • list - A list of file names in the specified path.

Raises:

  • HTTPException - If there's an error listing the files.

select_file​

@app.get('/select-file')
async def select_file(file: str, request: Request)

Retrieve the content of a specified file.

To select a file:

curl http://localhost:3000/api/select-file?file=<file_path>

Arguments:

  • file str - The path of the file to be retrieved. Expect path to be absolute inside the runtime.
  • request Request - The incoming request object.

Returns:

  • dict - A dictionary containing the file content.

Raises:

  • HTTPException - If there's an error opening the file.

upload_file​

@app.post('/upload-files')
async def upload_file(request: Request, conversation_id: str,
                      files: list[UploadFile])

Upload a list of files to the workspace.

To upload a files:

curl -X POST -F "file=@<file_path1>" -F "file=@<file_path2>" http://localhost:3000/api/upload-files

Arguments:

  • request Request - The incoming request object.
  • files list[UploadFile] - A list of files to be uploaded.

Returns:

  • dict - A message indicating the success of the upload operation.

Raises:

  • HTTPException - If there's an error saving the files.

save_file​

@app.post('/save-file')
async def save_file(request: Request)

Save a file to the agent's runtime file store.

This endpoint allows saving a file when the agent is in a paused, finished, or awaiting user input state. It checks the agent's state before proceeding with the file save operation.

Arguments:

  • request Request - The incoming FastAPI request object.

Returns:

  • JSONResponse - A JSON response indicating the success of the operation.

Raises:

HTTPException:

  • 403 error if the agent is not in an allowed state for editing.
  • 400 error if the file path or content is missing.
  • 500 error if there's an unexpected error during the save operation.