# 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](commands.md) as `"user": "root"` to change its ownership.
The examples use `$SANDBOX` for the sandbox ID, as in the [quickstart](quickstart.md).
## 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.
```bash
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
```
```json
{ "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.
```bash
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](commands.md#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.
```bash
curl "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files/list?path=/home/user/data" \
-H "Authorization: Bearer $KELN_API_KEY"
```
```json
{
"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](commands.md).
## 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`.
```bash
curl "https://sandbox.keln.ai/v1/sandboxes/$SANDBOX/files/stat?path=/home/user/data" \
-H "Authorization: Bearer $KELN_API_KEY"
```
```json
{
"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`.
```bash
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`.
```bash
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`.
```bash
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](pause-resume.md). Resume it first. |
| `409 sandbox_not_running` | The sandbox has stopped and its files are no longer available. |
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.
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.
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.