# Files

## Endpoint Summary

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/files` | List a workspace directory |
| `POST` | `/v1/files/read` | Read a workspace file as structured text |
| `GET` | `/v1/files/raw` | Stream raw bytes with content type and range support |
| `HEAD` | `/v1/files/raw` | Inspect raw-file response metadata |

## Directory Listing

`GET /v1/files?path=<relative-or-absolute>` returns directory entries for the active or requested workspace.

## File Read

`POST /v1/files/read` accepts a JSON body with `path` plus optional `offset`,
`limit`, and `allow_outside_cwd`. `GET /v1/files/raw?path=<path>` is intended for
browser previews and media/file downloads; HEAD has the same path resolution
without returning the body.

File operations are subject to workspace, auth, and profile restrictions. Remote clients should not assume arbitrary filesystem access.