File and Credential Endpoints
Last updated
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 |