API Reference#

This document covers the APIs used by the AI Teaching Assistant React UI.

Base URLs#

Direct service ports (default local runtime):

  • kiosk-core: http://127.0.0.1:8012

  • rag-service: http://127.0.0.1:8020

  • text-to-speech: http://127.0.0.1:8011

  • audio-analyzer: http://127.0.0.1:8010

Browser-facing same-origin proxy (recommended for UI):

  • /api/kiosk/* -> kiosk-core

  • /api/rag/* -> rag-service

  • /api/tts/* -> text-to-speech

  • /api/analyzer/* -> audio-analyzer

Health#

kiosk-core#

GET /health

Response:

{"status": "ok"}

rag-service#

GET /health

Response:

{"status": "ok"}

Session APIs (kiosk-core)#

Start Browser Stream Session#

POST /api/v1/sessions/start-stream

Starts a session and returns immediately with a session_id.

Request body (typical):

{
  "sample_rate": 16000,
  "chunk_seconds": 5.0,
  "silence_timeout_seconds": 2.0,
  "max_session_seconds": 60.0,
  "silence_threshold": 80,
  "language": "en",
  "temperature": 0.0,
  "tts_model": "speecht5",
  "tts_language": "English",
  "history": []
}

Response: session snapshot object with status: "running".

Start Session After Wake Word (Host Microphone)#

POST /api/v1/sessions/start-after-wakeword

Waits on the host microphone until the wake word is detected, then starts a normal microphone session and returns its snapshot.

Request body (example):

{
  "sample_rate": 16000,
  "chunk_seconds": 5.0,
  "silence_timeout_seconds": 1.5,
  "max_session_seconds": 20.0,
  "silence_threshold": 900,
  "wakeword_model": "hey jarvis",
  "wakeword_threshold": 0.5,
  "wakeword_vad_threshold": 0.4,
  "wakeword_patience_frames": 2,
  "wakeword_timeout_seconds": 0,
  "wakeword_inference_framework": "onnx"
}

Notes:

  • sample_rate must be 16000 for wake-word detection.

  • This endpoint listens on the kiosk host microphone, not browser audio chunks.

Start Browser Wake-Word Session (Cross-Machine)#

POST /api/v1/wakeword/start

Creates a wake-word detector session that processes browser-streamed WAV chunks.

Request body:

{
  "sample_rate": 16000,
  "wakeword_model": "hey jarvis",
  "wakeword_threshold": 0.5,
  "wakeword_vad_threshold": 0.4,
  "wakeword_patience_frames": 2,
  "wakeword_inference_framework": "onnx"
}

Response:

{
  "wakeword_session_id": "...",
  "status": "listening"
}

Push Browser Wake-Word Audio Chunk#

POST /api/v1/wakeword/{wakeword_session_id}/audio

Request headers:

  • Content-Type: audio/wav

Response:

{
  "wakeword_session_id": "...",
  "detected": false,
  "score": 0.12,
  "detected_label": "hey_jarvis"
}

Stop Browser Wake-Word Session#

POST /api/v1/wakeword/{wakeword_session_id}/stop

Response:

{
  "wakeword_session_id": "...",
  "status": "stopped"
}

Push Audio Chunk#

POST /api/v1/sessions/{session_id}/audio

Request headers:

  • Content-Type: audio/wav

Body:

  • WAV bytes for one browser chunk

Response:

{"status": "accepted"}

End Audio Stream#

POST /api/v1/sessions/{session_id}/audio/end

Signals end-of-stream so session finalization and response generation can complete.

Response:

{"status": "eos_accepted"}

Get Session Snapshot#

GET /api/v1/sessions/{session_id}

Used by UI polling.

Important fields:

  • status: created | running | stopping | completed | failed

  • transcript: combined transcript

  • response: streamed answer text

  • tts_audio_segments: generated audio clip metadata

  • tts_errors: synthesis errors, if any

  • captured_audio_seconds

  • end_reason

List Sessions#

GET /api/v1/sessions

Returns all known session snapshots in memory.

Stop Session#

POST /api/v1/sessions/{session_id}/stop

Requests early stop of a running session.

Response Audio Clip#

GET /api/v1/sessions/{session_id}/response-audio/{index}

Returns WAV audio for playback.

Device and System APIs (kiosk-core)#

List Input Devices#

GET /api/v1/devices

Returns host microphone devices (used for host capture workflows and diagnostics).

Runtime Metrics#

GET /api/v1/metrics

Proxies metrics-collector response.

Platform Info#

GET /api/v1/platform-info

Proxies hardware/platform summary from metrics-collector.

Knowledge Base APIs (rag-service)#

Ingest Files (Batch)#

POST /api/v1/context/file

Multipart upload. Supports .txt, .md, .docx, .pdf.

Response includes:

  • total_chunks_added

  • files_processed

  • files_succeeded

  • files_failed

  • per-file results

Clear Context#

DELETE /api/v1/context

Clears current vector collection documents.

Response:

{"status": "cleared"}

If clear fails, returns status failed and error details.

Context Stats#

GET /api/v1/context/stats

Returns collection-level statistics.

RAG Performance#

GET /api/v1/performance

Returns retrieval and LLM latency summaries.

Service Performance APIs#

TTS Performance#

GET /v1/performance on text-to-speech

ASR Performance#

GET /v1/performance on audio-analyzer