Skip to content

Files

Use the Files API to upload, download, and manage files and directories inside a sandbox.

All paths must be absolute. For GET, PUT, and DELETE requests, pass the path as a URL-encoded path query parameter. Relative paths return 400 invalid_path.

File operations run as the sandbox's default user. If user doesn't have permission to access a path, the API returns 403 permission_denied. To access it, run a command as "user": "root" to change its ownership.

The examples use $SANDBOX for the sandbox ID, as in the quickstart.

Write a file

PUT /v1/sandboxes/{sandbox_id}/files?path= writes the raw request body to a file.

Uploads are streamed, so the API doesn't impose a file size limit. The file must fit on the sandbox's disk.

If the file already exists, it's replaced. Missing parent directories are created automatically.

curl -X PUT "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files?path=/home/user/data/input.csv" \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @input.csv
{ "object": "file", "path": "/home/user/data/input.csv", "size": 2048 }

size is the number of bytes written. If the path points to a directory, the API returns 409 is_a_directory.

Read a file

GET /v1/sandboxes/{sandbox_id}/files?path= streams the raw file contents.

curl -o output.csv "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files?path=/home/user/data/output.csv" \
  -H "Authorization: Bearer $KELN_API_KEY"

Command output arrives line by line. See Output format. Use the Files API when you need the exact bytes, including binary data.

List a directory

GET /v1/sandboxes/{sandbox_id}/files/list?path= returns the entries in a directory.

curl "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files/list?path=/home/user/data" \
  -H "Authorization: Bearer $KELN_API_KEY"
{
  "object": "list",
  "path": "/home/user/data",
  "data": [
    {
      "name": "input.csv",
      "path": "/home/user/data/input.csv",
      "type": "file",
      "size": 2048,
      "modified_at": 1793740900
    }
  ]
}

type is either file or dir. Symbolic links are listed as file, including links to directories.

To inspect symbolic links, run ls -l using a command.

Describe a path

GET /v1/sandboxes/{sandbox_id}/files/stat?path= returns information about a path, following symbolic links.

If the path doesn't exist, the API returns 404 file_not_found.

curl "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files/stat?path=/home/user/data" \
  -H "Authorization: Bearer $KELN_API_KEY"
{
  "object": "file_stat",
  "path": "/home/user/data",
  "type": "dir",
  "size": null,
  "modified_at": 1793740900
}

type can be file, dir, or other. The other type includes devices, sockets, and pipes.

For files, size is reported in bytes.

Make a directory

POST /v1/sandboxes/{sandbox_id}/files/mkdir creates a directory and any missing parent directories.

The response uses the same format as stat. If the directory already exists, the API returns its current information. If a file blocks the path, it returns 409 not_a_directory.

curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files/mkdir \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/results/today"}'

Move or rename

POST /v1/sandboxes/{sandbox_id}/files/move moves a file or directory from from to to.

The response returns information about the destination in the same format as stat.

curl https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files/move \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "/home/user/data/output.csv", "to": "/home/user/results/today/output.csv"}'
  • to must specify the full destination path, including the file or directory name.
  • If to already exists, the API returns 409 path_exists unless you set "overwrite": true. Non-empty directories cannot be overwritten.
  • The parent directory of to must already exist. Otherwise, the API returns 404 file_not_found with param: to.

Delete a file

DELETE /v1/sandboxes/{sandbox_id}/files?path= deletes a file or symbolic link and returns 204.

Deleting a symbolic link doesn't delete its target.

Directories cannot be deleted through this endpoint, even if they're empty. The API returns 409 is_a_directory. To remove a directory, run a command such as rm -r.

curl -X DELETE "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files?path=/home/user/data/input.csv" \
  -H "Authorization: Bearer $KELN_API_KEY"

Errors

Code Meaning
400 invalid_path The path is missing or not absolute.
403 permission_denied The default user doesn't have permission to access this path.
404 file_not_found The path doesn't exist.
409 is_a_directory The path is a directory, but the operation requires a file.
409 not_a_directory A file blocks the directory path.
409 path_exists The destination already exists and overwrite is not true.
409 sandbox_paused The sandbox is paused. Resume it first.
409 sandbox_not_running The sandbox has stopped and its files are no longer available.