# Mock Interview — API contract for agents

Base URL: the deployed app origin (e.g. https://voice-interview-coach-c3jzuvtu.sauna.new).
The app exposes a fully public, no-login voice mock interview platform for software engineering candidates with two modes.

## Modes

- **Practice Arena** — six fixed questions (mixed technical + behavioral), your pace. Each question is read aloud via ElevenLabs, you answer by recording or typing, get a per-question score + feedback, and at the end you download a full markdown report.
- **Live Interview** — single-shot, continuous conversation with an animated AI interviewer (Meet-style two-tile UI with your webcam and a talking avatar). You decide when to end. Each turn: you speak (or type), the server transcribes → generates a contextual reply → generates spoken audio → returns the reply text and audio in one HTTP roundtrip. Conversation transcript is persisted; at the end you download a full markdown report.

## Practice Arena API

### POST /api/sessions
Start a new Practice Arena session.
Request: empty body.
Response: `{"sessionId":"<uuid>","totalQuestions":6,"question":{"idx":0,"type":"technical","text":"..."}}`.

### POST /api/tts
Generate spoken audio for arbitrary text (used internally; can be called directly).
Request: `{"text":"..."}` (JSON, plain text — strip markdown before sending).
Response: `audio/mpeg` bytes.

### POST /api/sessions/:id/answer
Submit one Practice Arena answer.
Request (multipart/form-data, field `audio`): an audio blob (webm works) of the spoken answer.
Request (alternative, JSON): `{"answerText":"<typed answer>"}`.
Response (when more questions remain): `{"transcript":"...","feedback":"...","score":<1-10>,"done":false,"next":{"idx":<n>,"type":"technical|behavioral","text":"..."}}`.
Response (when session is complete): `{"transcript":"...","feedback":"...","score":<1-10>,"done":true}`.

### GET /api/sessions/:id/report
Download the full markdown debrief (per-question scores, feedback, transcript, overall summary). Served as `Content-Disposition: attachment; filename="mock-interview-report-<id>.md"`.

## Live Interview API

### POST /api/live/start
Start a new Live Interview session.
Request: `{"style":"friendly|challenging|senior"}` (defaults to "senior").
Response: `{"sessionId":"<uuid>","style":"..."}`.

### POST /api/live/:id/turn
Send one turn of the conversation. Synchronously runs STT → LLM (streaming) → TTS and returns the full reply in one roundtrip.
Request (multipart/form-data, field `audio`): an audio blob (webm) of your spoken turn.
Request (alternative, JSON): `{"answerText":"<typed turn>"}`.
Response: `{"transcript":"<your speech as transcribed>","replyText":"<AI's reply>","replyAudioBase64":"<mp3 bytes, base64>"}`.
On TTS failure, `replyAudioBase64` is empty and `ttsWarning` is populated; `replyText` is still reliable.

### POST /api/live/:id/end
Mark the session completed. Call when the user ends the call.

### GET /api/live/:id/report
Download the full markdown debrief (overall impression, strengths, areas to improve, full transcript with interviewer/candidate turns). Served as `Content-Disposition: attachment; filename="live-interview-report-<id>.md"`.

## External dependencies

- `https://sauna.local/v1/llms/responses` — LLM for question gen + feedback + replies (metered to app owner).
- `https://sauna.local/v1/elevenlabs/v1/text-to-speech/...` — TTS (metered to app owner).
- `https://sauna.local/v1/elevenlabs/v1/speech-to-text` — STT (metered to app owner).

No external accounts or API keys required from the end user.