​
Purpose

Quick Help calling provides a real-time voice assistance flow for learners using LiveKit-backed sessions and transcript persistence. The backend entrypoint is src/apis/quick_help.py, with domain behavior in src/core/voice_assistance/service.py.

​
Core flow

  1. Client starts a session with POST /api/v1/quick-help/sessions.
  2. Backend creates a session document, provisions/mints LiveKit join credentials, and returns session metadata.
  3. Client and internal voice agent append transcript chunks over time.
  4. Client ends the call with POST /api/v1/quick-help/sessions/{session_id}/end.
  5. Backend finalizes the session, and optionally triggers summarization/next-step generation.

​
API endpoints

User-facing endpoints:
  • POST /api/v1/quick-help/sessions — create session and receive call credentials.
  • GET /api/v1/quick-help/sessions/{session_id} — fetch caller-owned session state.
  • GET /api/v1/quick-help/sessions/{session_id}/transcript — fetch transcript + summary snapshot.
  • POST /api/v1/quick-help/sessions/{session_id}/transcript — append transcript utterances from caller/client.
  • POST /api/v1/quick-help/sessions/{session_id}/end — end session and optionally summarize.
Internal agent endpoints:
  • GET /api/v1/quick-help/internal/sessions/{session_id}/context — fetch session context for voice agent runtime.
  • POST /api/v1/quick-help/internal/sessions/{session_id}/transcript — append transcript utterances from agent pipeline.
For exact request/response schemas, use the API reference tab (quick-help tag), sourced from docs/api-reference/openapi.public.json.

​
Auth and access model

  • User endpoints require authenticated user context and enforce organization + ownership checks.
  • Internal endpoints require X-Quick-Help-Agent-Key, validated server-side by Quick Help service configuration.
  • Cross-organization access is rejected.

​
Session and transcript behavior

  • Session status transitions are managed server-side (create, active, ended/failure).
  • Transcript append APIs are additive and keep a canonical per-session transcript record.
  • Transcript fetch returns a stable payload shape even when no utterances exist yet.

​
Cost and usage linkage

Quick Help usage contributes to AI usage accounting via per-minute tracking fields (quick_help_minutes) and pricing (quick_help_price_per_minute) in AI usage events. See AI usage and cost tracking for pricing precedence and reporting behavior.

​
Operational notes

  • Keep session ownership and org checks intact whenever adding new Quick Help endpoints.
  • Coordinate payload changes with frontend call clients and any internal voice worker integrations.
  • If you add/modify routes, regenerate OpenAPI docs:
uv run python scripts/dev/export_openapi_for_docs.py