> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

File routes read and write a `running` sandbox's filesystem directly, without an exec. They are served by the data plane with a [token](https://developers.telnyx.com/docs/edge-compute/sandboxes/authentication.md#sandbox-token), never by the control plane. Every route takes the file's absolute path in `?path=`.

## Writing

`PUT /sandbox/{id}/files?path=` writes the request body as the file's contents. Missing parent directories are created. The response is `201` for a new file and `200` for a replaced one. The CLI's `cp` copies one regular file, and a sandbox path ending in `/` takes the local file's name.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu cp ./data.csv doc-run-42:/workspace/
```

```bash API theme={null}
curl -X PUT \
  "$DATA_API/$SANDBOX_ID/files?path=/workspace/data.csv" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv
```

```text Output theme={null}
Copied 19 bytes to sb-us-east-2-01a1d753-025a-75a9-b353-ee17f60f17e3:/workspace/data.csv
```

The replace is atomic. A reader sees the old file or the new one, never a partial write, and an existing file keeps its mode and owner. `?directory=true` with no body creates a directory.

## Reading

`GET /sandbox/{id}/files?path=` returns the file's bytes as `application/octet-stream`, with its `Content-Length`. `HEAD` returns the headers only. With the CLI, a local directory takes the sandbox file's name, and `-` writes the file to stdout.

```bash Workstation theme={null}
telnyx-edge sandbox-cpu cp doc-run-42:/workspace/report.json .
```

```bash API theme={null}
curl "$DATA_API/$SANDBOX_ID/files?path=/workspace/report.json" \
  -H "Authorization: Bearer $SANDBOX_TOKEN" -o report.json
```

```text Output theme={null}
Copied 12 bytes from sb-us-east-2-01a1d753-025a-75a9-b353-ee17f60f17e3:/workspace/report.json to report.json
```

A transfer interrupted midway can retain status `200` while the body is shorter than `Content-Length`. Compare the received byte count with `Content-Length` and reject a mismatch, even if the HTTP library reports a clean end of stream. Discard an incomplete download and retry the whole request. A `Range` header is ignored, and the whole file is returned.

## Listing

`?list=true` returns a directory's entries, 20 per page and at most 100. `?stat=true` returns the entry of the path itself. A symbolic link is reported as a link, not followed.

```json Output theme={null}
{
  "data": {
    "path": "/workspace/report.json",
    "name": "report.json",
    "type": "file",
    "size_bytes": 18234,
    "modified_at": "2026-11-11T19:21:07Z",
    "mode": 420,
    "uid": 0,
    "gid": 0
  }
}
```

| Field | Description |
| - | - |
| `type` | `file`, `directory`, `symlink`, or `other`. |
| `mode` | The permission bits, including setuid, setgid, and sticky, as a decimal integer. `420` is `0644`. |
| `uid`, `gid` | The numeric owner and group. |

## Renaming and Deleting

`POST /sandbox/{id}/files/rename` renames a path. The response is `204`.

```json Request theme={null}
{ "from": "/workspace/draft.md", "to": "/workspace/final.md" }
```

The target's parent must exist. A rename across filesystems, such as from `/` to `/workspace`, is refused with `409 cross_device`.

`DELETE /sandbox/{id}/files?path=` deletes a file or an empty directory. The response is `204`. `?recursive=true` deletes a directory and its contents. A non-empty directory without it is refused with `409 directory_not_empty`.

## Sizes

| Limit | Value |
| - | - |
| File size | 512 MiB. The request's `Content-Length` is checked before the body is read, and a larger write is refused with `413 file_too_large`. |
| Streaming | Files over 8 MiB are streamed without buffering the whole file. Uploads use 8 MiB chunks; downloads are read internally in 1 MiB pieces and returned as one continuous response, not client-addressable HTTP ranges. |
| Progress | An upload's first byte within 60 seconds, then each 8 MiB chunk within 5 minutes; each 1 MiB download piece must be consumed within 5 minutes. Missing a download deadline ends the response early: apply the byte-count check above. |
| Concurrent transfers over 8 MiB | 4 per organization and 32 total on each API replica, shared by uploads and downloads. These are per-replica limits, not site-wide limits. Either limit can cause `503`, even below your organization's limit if the replica is full; honor `Retry-After` before retrying. |

An `Idempotency-Key` on a `PUT` is accepted for bodies up to 8 MiB. A larger upload that carries one is refused with `400`.

## Paths

* **Format.** Absolute, at most 4,096 bytes of UTF-8, not ending in `.` or `..`. An invalid path is refused with `422 invalid_path`.
* **Missing.** A path that does not exist is `404`.
* **Kind.** A write on a directory, or a directory write on a file, is refused with `409 path_type_mismatch`. A read, a `HEAD`, or `?list=true` on the wrong kind of path is refused with `422 invalid_path`.
* **Reserved.** Writes, renames, and deletes under `/.telnyx` are refused with `422 invalid_path`, whether or not the directory exists.
* **Owner.** File requests run as `root`.

Every file request counts as activity for `idle_timeout`. File requests to a paused sandbox are refused with `409 sandbox_paused`.
