Interview

The interview module offers two modes: a turn-based REST flow (text), and a realtime WebSocket that proxies a voice model.

REST (turn-based)

Start a session, then exchange messages by session_id.

Action	Method & path
Start	`POST /api/interview/start`
Send a message	`POST /api/interview/chat`
End session	`DELETE /api/interview/session/:sessionId`

Start


// POST /api/interview/start
{
  "resume_context": "Senior FE, 6y React, led design system…",
  "job_description": "We need a frontend lead…",
  "role": "frontend",
  "config": { "model": "gpt-4o-mini" }
}

Returns a session (including the session_id) and the opening question.

Chat


// POST /api/interview/chat
{ "session_id": "sess_abc", "message": "I'd start by auditing the component API…" }

Returns the interviewer’s next turn.

Delete


curl -X DELETE http://localhost:3112/api/interview/session/sess_abc

Frees the session’s server-side state.

Field (start)	Type	Required
`resume_context`	`string`	✅
`job_description`	`string`	—
`role`	`string`	—
`config`	`object`	—

Realtime (voice) WebSocket

For a live voice interview, connect to the realtime endpoint. It is not a Nest gateway — main.ts attaches it to the raw HTTP server, so it lives at:


ws://localhost:3112/api/interview/realtime/:sessionId

The service upgrades the connection and proxies upstream to an OpenAI-compatible realtime API, relaying audio/text both ways. Configure it via query params:

Query param	Purpose
`api_key`	Upstream API key (or sent as a bearer header)
`model`	Realtime model name
`base_url`	Upstream base URL (defaults to OpenAI realtime)
`role`	Interviewer persona / role (falls back to the session’s role)


const ws = new WebSocket(
  'ws://localhost:3112/api/interview/realtime/sess_abc' +
    '?model=gpt-4o-realtime-preview&role=frontend&api_key=sk-...'
)
 
ws.onmessage = (e) => handleRealtimeFrame(JSON.parse(e.data))
ws.onopen = () => ws.send(JSON.stringify({ type: 'response.create' }))

The realtime socket relays your api_key to the upstream provider. Terminate it behind your own gateway and inject the key server-side — never ship a real provider key to a browser client.

Start a REST session first to establish server-side interview state (resume context, role); the realtime socket can then reference the same sessionId.