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

# Voice API

> REST endpoints for PTT, continuous listening, wake word status, and voice device management.

## GET /voice/status

Get the current state of all voice subsystems.

```bash theme={null}
curl http://localhost:7432/api/v1/voice/status
```

```json theme={null}
{
  "runtime_available": true,
  "continuous_available": false,
  "continuous_listening": false,
  "ptt_available": true,
  "ptt_is_recording": false,
  "wake_detector_active": true,
  "is_handoff_active": false,
  "stt_available": true,
  "tts_available": true
}
```

## POST /voice/ptt/start

Start a PTT recording session.

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/voice/ptt/start
```

```json theme={null}
{ "started": true }
```

## POST /voice/ptt/stop

Stop PTT recording and return the transcript.

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/voice/ptt/stop
```

```json theme={null}
{
  "transcript": "What is the weather today?",
  "response": "It is currently 22°C and sunny in London.",
  "stopped": true
}
```

## POST /voice/continuous/start

Start continuous voice listening mode.

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/voice/continuous/start
```

```json theme={null}
{ "started": true }
```

## POST /voice/continuous/stop

Stop continuous listening.

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/voice/continuous/stop
```

```json theme={null}
{ "stopped": true }
```

## GET /voice/devices

List available audio input/output devices.

```bash theme={null}
curl http://localhost:7432/api/v1/voice/devices
```

```json theme={null}
{
  "input": [
    { "name": "Built-in Microphone", "index": 0 },
    { "name": "USB Headset", "index": 1 }
  ],
  "output": [
    { "name": "Built-in Speakers", "index": 0 },
    { "name": "USB Headset", "index": 1 }
  ],
  "active": {
    "input_device": "USB Headset",
    "output_device": "Built-in Speakers"
  }
}
```

## POST /settings/voice

Persist STT settings to `config.toml`. Only `stt`, `stt_model`, and `stt_device` are accepted — a gateway restart is required before they take effect (there's no live TTS/device settings write path yet).

```bash theme={null}
curl -X POST http://localhost:7432/api/v1/settings/voice \
  -H "Content-Type: application/json" \
  -d '{
    "stt": "whisper",
    "stt_model": "small",
    "stt_device": "cpu"
  }'
```

```json theme={null}
{ "ok": true, "restart_required": true, "updated_fields": ["stt", "stt_model", "stt_device"] }
```