# File and Credential Endpoints

Endpoints for files, stored keys and live voice.

| Method | Path | Description |
|---|---|---|
| `GET` `PUT` | `/v1/file` | **local** — `GET ?path=` returns the file with an `X-Content-SHA256` header (400 for a directory, 404 when missing). `PUT` `{path, content \| content_base64, base_sha256}` writes it and returns `{sha256, path}`; 409 (with `current_sha256`) when the file changed on disk since `base_sha256`, or when it no longer exists. Paths resolve against the home directory and must stay inside it; sensitive paths return 403 |
| `GET` | `/v1/file/open` | **local** — `?path=`. Opens a file with the OS default handler and returns `{result}`. Same home-only and sensitive-path rules as `/v1/file`; URLs are not accepted here |
| `GET` | `/v1/file/locate` | **local** — find candidate paths for a bare file name and return `{paths}`. `name` must be a bare name; `size` is required unless `dir=1` (400 otherwise); `child` (repeatable, directories only) and `mtime` (ms, within 1 s) narrow the match. Searches `Desktop`, `Downloads`, `Documents`, `Pictures`, `Movies`, `Music`, `Library/Mobile Documents`, then the rest of home, and stops at the first of those roots with a match (8 s budget) |
| `GET` | `/v1/workdir` | **local** — resolve and validate a work directory (`?path=`, empty means home), returning `{path}`; 400 when it cannot be resolved, does not exist, or is not a directory |
| `DELETE` | `/v1/key` | **local** — `?key=`. Deletes a single credential from the keychain and from the key list in `config.json`. The `GET` that returned a stored value was removed in v1.0.23 |
| `GET` `POST` | `/v1/keys` | **local** — `GET` returns `keys`, the names registered in `config.json` (never the values). `POST` `{key, value}` (both required) writes the keychain and registers the name |
| `GET` | `/v1/voice/live` | **local** — added in v1.1.1. WebSocket upgrade that relays the dashboard's voice mode to Gemini Live (`gemini-3.8-live`) with `GEMINI_API_KEY` from the keychain. The daemon sends the setup itself — voice system prompt in the configured reply language, the `send_to_chat` / `read_history` / `read_task` function declarations, input and output transcription — then passes frames both ways. Closes with code `4401` when the key is missing and `1011` when the upstream dial or setup fails |